Skip to main content
@copass/datasource-fs is the official filesystem driver for Copass. It scans, diffs, and watches a local directory, pushing every file event through a registered data source. It’s what the CLI uses internally for copass index and copass watch. Use this when you want filesystem-backed ingestion inside your own Node app — a background worker, a custom CLI, an Electron app, a CI hook.

​
Install

npm install @copass/datasource-fs @copass/core

​
FileSystemDataSource.create

Idempotent factory — registers the data source the first time, reuses it thereafter. 
import { CopassClient } from '@copass/core';
import { FileSystemDataSource } from '@copass/datasource-fs';

const client = new CopassClient({
  auth: { type: 'api-key', key: process.env.COPASS_API_KEY! },
});

const sandbox = await client.sandboxes.create({
  name: 'repo-index',
  owner_id: 'owner-uuid',
});

const fs = await FileSystemDataSource.create({
  client,
  sandboxId:   sandbox.sandbox_id,
  projectPath: '/path/to/repo',
  name:        'my-repo',            // defaults to basename(projectPath)
});

​
Full index

One-shot scan of the tree. Honors .gitignore and the indexing config on the sandbox. 
const summary = await fs.fullIndex({
  onProgress: (msg) => console.log(msg),
});

console.log(summary);
// {
//   file_count:    482,
//   indexed_count: 479,
//   error_count:   3,
//   skipped_count: 0,
//   duration_ms:   28_104,
//   errors:        [{ file: '…', error: '…' }]
// }
Options:
  • dryRun: true — return the discovered file list without pushing anything.
  • onProgress: (msg) => … — progress updates suitable for a spinner or log line.
  • maxFiles: N — cap the run.

​
Continuous watching

await fs.start();         // start chokidar; returns after initial reconcile
// … keep process alive …
await fs.stop();          // tear down, flush pending
Every filesystem event is coalesced, debounced, and pushed through the same data source with an auto-derived source_type (code for recognized languages, markdown / json / text otherwise). Inspect the most recent reconcile summary: 
console.log(fs.lastReconcileSummary);
// { upserts, deletes, renames, errors, durationMs }

​
One-shot incremental diff

Perfect for a CI job that runs every commit without holding chokidar open: 
const summary = await fs.reconcile();
console.log(summary.upserts, summary.deletes, summary.renames);
State is persisted to <projectPath>/.olane/watch-state.json between runs so only changed files are re-pushed.

​
Lifecycle inheritance

FileSystemDataSource extends BaseDataSource, so it inherits the standard data-source lifecycle verbs: 
await fs.pause();         // flip source status → 'paused'
await fs.resume();        // → 'active'
await fs.disconnect();    // → 'disconnected'
await fs.describe();      // re-fetch the DataSource record
See Secure Storage for what these status transitions mean.

​
Power-user exports

For callers that want to integrate at a lower level than FileSystemDataSource: 
import {
  runFullIndex,
  ProjectWatchRuntime,
  scanProjectFiles,
  diffFiles,
  readWatchState,
  writeWatchState,
  installWatchService,
  uninstallWatchService,
  getWatchServiceStatus,
} from '@copass/datasource-fs';
These are the primitives FileSystemDataSource is built on — reach for them when you want custom watch semantics or to drive indexing from your own orchestration layer.

​
Service install (launchd / systemd)

Run the watcher as a user-level background service instead of a foreground process: 
import { installWatchService, uninstallWatchService } from '@copass/datasource-fs';

await installWatchService('/path/to/repo', '/path/to/your/bin');
// … later …
await uninstallWatchService('/path/to/repo', '/path/to/your/bin');
Platform-specific descriptors (launchd plist on macOS, systemd --user unit on Linux, Task Scheduler entry on Windows) are generated and installed automatically. The CLI uses this internally for copass watch install-service.

​
Next steps

  • SDK — build your own driver by subclassing BaseDataSource from @copass/core.
  • Secure Storage — the containment model this driver operates inside.
  • CLI — if you just want filesystem indexing without writing code.