process-graph 1.2.0 → 1.3.0

package/README.md

@@ -40,24 +40,26 @@ deriveStatuses(model, { submit: "done" }, facts); // Map { "submit" => "done", "
 
 The package is built from the repository's internal packages, which are bundled into it and not published on their own; each internal package's README documents its functions and rules. Each subpath loads only the code it reaches.
 
-| Import                               | What it is                                                                                                                                                                         | Runs in               |
-| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
-| `process-graph`                      | The model (`defineModel`, `parseModel`, `validate`), its projections and inverses, and the reasoning over a run (statuses, ready set, blocked-by, impact, what-if, critical path). | Browser, Worker, Node |
-| `process-graph/layout`               | `layout`: positions for a projected flowchart, swimlane or state machine, in the model's `views` shape, through elkjs.                                                             | Browser, Worker, Node |
-| `process-graph/source/github`        | The `GraphSource` port (contract, schemas, router, pagination and an in-memory fake) and the GitHub issues adapter, `createGitHubIssuesSource`.                                    | Browser, Worker, Node |
-| `process-graph/source/github/node`   | `githubTokenFromEnvironment`: a token port reading `GITHUB_TOKEN` or the GitHub CLI's token.                                                                                       | Node                  |
-| `process-graph/store`                | The `GraphStore` port (contract, schemas, router, change feed, structural queries and an in-memory fake) and the SQLite store over any Drizzle SQLite database.                    | Browser, Worker, Node |
-| `process-graph/store/node`           | `openNodeGraphStore`: the SQLite store on Node's built-in `node:sqlite`.                                                                                                           | Node                  |
-| `process-graph/store/wasm`           | `connectGraphStore`: connects a page to the store a dedicated worker serves.                                                                                                       | Browser               |
-| `process-graph/store/wasm/worker`    | `serveGraphStoreInWorker`: serves the store from a dedicated worker on SQLite wasm and OPFS, shared between tabs with no special headers.                                          | Dedicated worker      |
-| `process-graph/react`                | Headless React hooks and unstyled components: follow a stored model, derive its run, project, filter and select.                                                                   | Browser               |
-| `process-graph/ui`                   | Styled components over `process-graph/react`, the SVG sequence diagram and the theme contract with light and dark themes.                                                          | Browser               |
-| `process-graph/ui/style.css`         | The compiled styles for `process-graph/ui`.                                                                                                                                        | Browser               |
-| `process-graph/react-flow`           | React Flow views of a flowchart, swimlane or state machine, laid out by `process-graph/layout`.                                                                                    | Browser               |
-| `process-graph/react-flow/style.css` | The compiled styles for `process-graph/react-flow`, React Flow's own included.                                                                                                     | Browser               |
-| `process-graph/cli`                  | The command line as a library: `runCli` over injected ports, `nodePorts` for a Node process, and each command's operation returning plain data.                                    | Node                  |
-
-`zod` and `trilean`, which the root entry needs, are dependencies. The libraries only other subpaths need are optional peer dependencies, so installing `process-graph` for its root entry pulls in nothing else; install the peers of each subpath you import beside it:
+| Import                               | What it is                                                                                                                                                                                          | Runs in               |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
+| `process-graph`                      | The model (`defineModel`, `parseModel`, `validate`), its projections and inverses, and the reasoning over a run (statuses, ready set, blocked-by, impact, what-if, critical path).                  | Browser, Worker, Node |
+| `process-graph/layout`               | `layout`: positions for a projected flowchart, swimlane or state machine, in the model's `views` shape, through elkjs.                                                                              | Browser, Worker, Node |
+| `process-graph/source/github`        | The `GraphSource` port (contract, schemas, router, pagination and an in-memory fake) and the GitHub issues adapter, `createGitHubIssuesSource`.                                                     | Browser, Worker, Node |
+| `process-graph/source/github/node`   | `githubTokenFromEnvironment`: a token port reading `GITHUB_TOKEN` or the GitHub CLI's token.                                                                                                        | Node                  |
+| `process-graph/store`                | The `GraphStore` port (contract, schemas, router, change feed, structural queries and an in-memory fake) and the SQLite store over any Drizzle SQLite database.                                     | Browser, Worker, Node |
+| `process-graph/store/node`           | `openNodeGraphStore`: the SQLite store on Node's built-in `node:sqlite`; `prepareDataFile`: makes its data file and directory private before it opens.                                              | Node                  |
+| `process-graph/store/wasm`           | `connectGraphStore`: connects a page to the store a dedicated worker serves.                                                                                                                        | Browser               |
+| `process-graph/store/wasm/worker`    | `serveGraphStoreInWorker`: serves the store from a dedicated worker on SQLite wasm and OPFS, shared between tabs with no special headers.                                                           | Dedicated worker      |
+| `process-graph/react`                | Headless React hooks and unstyled components: follow a stored model, derive its run, project, filter and select.                                                                                    | Browser               |
+| `process-graph/ui`                   | Styled components over `process-graph/react`, the SVG sequence diagram and the theme contract with light and dark themes.                                                                           | Browser               |
+| `process-graph/ui/theme`             | The theme contract `vars`, `lightTheme`, `darkTheme`, `lightValues` and `darkValues` without the components, for a Vanilla Extract stylesheet that themes `process-graph/ui` without loading React. | Any                   |
+| `process-graph/ui/style.css`         | The compiled styles for `process-graph/ui`.                                                                                                                                                         | Browser               |
+| `process-graph/react-flow`           | React Flow views of a flowchart, swimlane or state machine, laid out by `process-graph/layout`.                                                                                                     | Browser               |
+| `process-graph/react-flow/style.css` | The compiled styles for `process-graph/react-flow`, React Flow's own included.                                                                                                                      | Browser               |
+| `process-graph/cli`                  | The command line as a library: `runCli` over injected ports, `nodePorts` for a Node process, each command's operation returning plain data, and `version`, this package's own.                      | Node                  |
+| `process-graph/package.json`         | The package's manifest, for reading its version or anything else it declares.                                                                                                                       | Any                   |
+
+`zod` and `trilean`, which the root entry needs, are dependencies; a project with an install age gate exempts `trilean` and `trilean-regex` beside `process-graph` (see [Install](../../../README.md#install)). The libraries only other subpaths need are optional peer dependencies, so installing `process-graph` for its root entry pulls in nothing else; install the peers of each subpath you import beside it:
 
 | Subpath             | Peer dependencies                                                            |
 | ------------------- | ---------------------------------------------------------------------------- |
@@ -69,10 +71,11 @@ The package is built from the repository's internal packages, which are bundled
 | `store/wasm/worker` | `@orpc/contract`, `@orpc/server`, `drizzle-orm`, `@sqlite.org/sqlite-wasm`   |
 | `react`             | `react`                                                                      |
 | `ui`                | `react`, `@vanilla-extract/recipes`, `@vanilla-extract/css` (types)          |
+| `ui/theme`          | `@vanilla-extract/css` (types)                                               |
 | `react-flow`        | `react`, `react-dom`, `@xyflow/react`, `elkjs`, `@vanilla-extract/recipes`   |
 | `cli` and the bin   | `commander`, `@orpc/client`, `@orpc/contract`, `@orpc/server`, `drizzle-orm` |
 
-The versions are the ones `package.json` declares under `peerDependencies`.
+The versions are the ones `package.json` declares under `peerDependencies`. A peer with a stable version is a caret range whose floor is the version this package is tested against, so any later compatible release satisfies it. The oRPC packages, `drizzle-orm` and `@sqlite.org/sqlite-wasm` are prereleases, which have no compatible-range semantics (a range on one admits only later prereleases of the same version, which may break anything), so each is declared at the exact version tested.
 
 With Vite, exclude `@sqlite.org/sqlite-wasm` from dependency pre-bundling (`optimizeDeps.exclude`), since it loads its `.wasm` file relative to itself. A worker module serving the browser store is one call:
 

package/dist/bin.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { t as exitCodes } from "./exit-codes-0ultCqdS.js";
+import { t as version } from "./version-Dagrkvwt.js";
 import { readFileSync } from "node:fs";
 //#region src/missing-peers.ts
 /**
@@ -66,7 +67,7 @@ const manifest = new URL("../package.json", import.meta.url);
 const declaredPeers = () => {
 	const parsed = JSON.parse(readFileSync(manifest, "utf8"));
 	if (typeof parsed !== "object" || parsed === null || !("peerDependencies" in parsed) || typeof parsed.peerDependencies !== "object" || parsed.peerDependencies === null) throw new Error(`${manifest.pathname} declares no peerDependencies`);
-	return new Map(Object.entries(parsed.peerDependencies).flatMap(([name, version]) => typeof version === "string" ? [[name, version]] : []));
+	return new Map(Object.entries(parsed.peerDependencies).flatMap(([name, specifier]) => typeof specifier === "string" ? [[name, specifier]] : []));
 };
 /** Whether a package resolves from this bin's own location, as the command line's imports would. Only a package that is not installed counts as missing; any other resolution error is the import's to report. */
 const resolves = (name) => {
@@ -83,10 +84,10 @@ if (missing.length > 0) {
 	process.stderr.write(missingPeersMessage(missing, declaredPeers(), process.env.npm_config_user_agent));
 	process.exitCode = exitCodes.missingPeers;
 } else {
-	const { packageVersion, runProcess } = await import("./dist-Cw63tKU9.js");
+	const { runProcess } = await import("./dist-81kTKnMq.js");
 	process.exitCode = await runProcess({
 		name: "process-graph",
-		version: packageVersion(manifest)
+		version
 	});
 }
 //#endregion

package/dist/cli.d.ts

@@ -1,9 +1,9 @@
-import { A as Facts, B as Status, _ as StatusRule, k as FactRecord, m as IncomingBasis, p as ArtefactBasis } from "./index-BH1aFqkJ.js";
-import { E as Participant, F as OverlayStatus, G as IdSpace, K as OpenIds, S as EventDef, a as Overlay, b as ArtefactDef, g as Model, k as Transition, x as Element } from "./index-CmZOswkx.js";
-import { C as Gap, n as GraphqlFetch, t as GitHubTokenPort, v as GraphSourceClient } from "./graphql-C1j5wQFz.js";
-import { ut as GraphStoreClient } from "./index-DxWOY8f9.js";
-import "./index-CptUHq6F.js";
-import { A as Flowchart, E as Swimlane, M as Handoff, g as SequenceDiagram, x as StateMachine } from "./index-CoA6vXqe.js";
+import { A as Facts, B as Status, _ as StatusRule, k as FactRecord, m as IncomingBasis, p as ArtefactBasis } from "./index-D4CnOhNf.js";
+import { A as Transition, C as EventDef, D as Participant, I as OverlayStatus, K as IdSpace, S as Element, _ as Model, o as Overlay, q as OpenIds, x as ArtefactDef } from "./index-Dvz_I_uQ.js";
+import { C as Gap, n as GraphqlFetch, t as GitHubTokenPort, v as GraphSourceClient } from "./graphql-BE7xm5dB.js";
+import { ut as GraphStoreClient } from "./index-CR8xUK3S.js";
+import "./index-hri2a13-.js";
+import { A as Flowchart, E as Swimlane, M as Handoff, g as SequenceDiagram, x as StateMachine } from "./index-D06bcdfw.js";
 import { ComputedValue } from "trilean";
 //#region ../graph-cli/dist/exit-codes.d.ts
 /**
@@ -118,6 +118,10 @@ interface NodePortsOptions {
   readonly env?: Readonly<Record<string, string | undefined>>;
   /** The home directory the default data path falls back on; the user's when absent. */
   readonly home?: string;
+  /**
+   * A data file the host owns, such as one under its own home directory. It becomes the default data path in place of `PROCESS_GRAPH_DATA` and the XDG data file, and it gets the treatment the command line gives its own XDG data file: its directory, and any missing directories above it, are created readable by the owner only and kept that way, the database is created owner-only before SQLite opens it, and an existing store others can read is narrowed, with a warning on standard error (see `prepareDataFile` in `process-graph/store/node`). A path given with `--data` still wins, and is treated as the user's. The XDG data file when absent.
+   */
+  readonly dataPath?: string;
   /** Supplies GitHub tokens; `GITHUB_TOKEN` or the GitHub CLI's token (`githubTokenFromEnvironment`) when absent. */
   readonly token?: GitHubTokenPort;
   /** How requests reach GitHub; the global `fetch` when absent. */
@@ -150,7 +154,7 @@ export declare const defaultDataPath: (env: Readonly<Record<string, string | und
  */
 export declare const packageVersion: (manifest: URL) => string;
 /**
- * The ports for a Node process: the SQLite store over `node:sqlite` (creating the data file's directory when needed), the GitHub issues source for `github:` scopes, the file system and the process's streams.
+ * The ports for a Node process: the SQLite store over `node:sqlite` (creating the data file's directory when needed, private when the command line or the host owns it), the GitHub issues source for `github:` scopes, the file system and the process's streams.
  * @param options - Replacements for any of the defaults.
  * @returns The ports.
  */
@@ -485,6 +489,30 @@ interface SyncRequest {
   /** A cursor from an interrupted sync: the first source's sync continues after it. */
   readonly after?: string;
 }
+/** Where a sync a source interrupted carries on, as data a host acts on; the command line renders it as the commands to run. */
+interface SyncInterruption {
+  /** The request that continues the failing source: its scopes, after the cursor of the last page read from it, or from the start when none was read. */
+  readonly resume: SyncRequest;
+  /** The scopes of the sources after the failing one, which were not read; sync them afresh once `resume` has finished. */
+  readonly remaining: readonly string[];
+  /** Whether pages read before the failure were written to the model. */
+  readonly saved: boolean;
+}
+/**
+ * Thrown by `sync` when a source fails part way. Its exit status and message are the source's failure, classified as `failureOf` classifies it; its cause is the error underneath that failure, such as the token port's own error; and what to run next is data, in `resume` and `remaining`, never text.
+ */
+export declare class SyncInterruptedError extends CliError implements SyncInterruption {
+  readonly resume: SyncRequest;
+  readonly remaining: readonly string[];
+  readonly saved: boolean;
+  /**
+   * @param exitCode - The exit status the source's failure maps to.
+   * @param message - The source's failure.
+   * @param interruption - Where the sync carries on.
+   * @param options - The underlying error, kept as the cause.
+   */
+  constructor(exitCode: CliError["exitCode"], message: string, interruption: SyncInterruption, options?: ErrorOptions);
+}
 /** What a sync wrote. */
 interface SyncResult {
   readonly modelId: string;
@@ -500,12 +528,12 @@ interface SyncResult {
 /**
  * Reads every page of the scopes from their sources and merges them into the session's model in one write, creating the model when the store has none. Records already in the model are replaced by identifier and the rest are kept, so syncing again refreshes what changed.
  *
- * When a source fails part way, the pages read before the failure are still written, and the error says how to resume: the failing source's scopes with `--after` and the cursor of its last page read.
+ * When a source fails part way, the pages read before the failure are still written, and the error carries where to carry on: the request that resumes the failing source after the cursor of its last page read, and the scopes of the sources not reached.
  * @param session - The store and model.
  * @param sources - The source for each identifier prefix.
  * @param request - The scopes, and a cursor to resume after.
  * @returns What was written, and the gaps the sources reported.
- * @throws CliError with `usage` for a scope with no source prefix, a prefix no source serves, or `after` with scopes of more than one source; and with the source's failure, the resume command added, when a source refuses the sync.
+ * @throws CliError with `usage` for a scope with no source prefix, a prefix no source serves, or `after` with scopes of more than one source; and SyncInterruptedError, with the source's failure and where to carry on, when a source fails part way.
  */
 export declare const sync: (session: GraphSession, sources: SourceLookup, request: SyncRequest) => Promise<SyncResult>;
 //#endregion
@@ -563,4 +591,8 @@ export declare const stateMachineToDot: <I extends IdSpace>(view: StateMachine<I
  */
 export declare const sequenceToDot: <I extends IdSpace>(view: SequenceDiagram<I>, participantLabel: (participant: I["actor"]) => string) => string;
 //#endregion
-export type { Addition, ArtefactState, BlockedResult, CliPorts, CyclesResult, ElementStatus, ElementSummary, ExitCode, FactsResult, Failure, FormatName, GraphSession, HandoffsResult, ImpactResult, NodePortsOptions, OpenedStore, PathResult, ProgramIdentity, ProjectedView, ReadyResult, SetArtefactResult, SetFactResult, SetResult, ShowRequest, ShowResult, SourceLookup, StoredRun, SyncRequest, SyncResult, ValidateResult, ValidationIssue, ViewName, WhyLink, WhyResult, Written };
+//#region src/version.d.ts
+/** The version of the installed `process-graph` package, as its manifest names it. The bundler writes it in when the package is built, so reading it touches no file. */
+export declare const version: string;
+//#endregion
+export type { Addition, ArtefactState, BlockedResult, CliPorts, CyclesResult, ElementStatus, ElementSummary, ExitCode, FactsResult, Failure, FormatName, GraphSession, HandoffsResult, ImpactResult, NodePortsOptions, OpenedStore, PathResult, ProgramIdentity, ProjectedView, ReadyResult, SetArtefactResult, SetFactResult, SetResult, ShowRequest, ShowResult, SourceLookup, StoredRun, SyncInterruption, SyncRequest, SyncResult, ValidateResult, ValidationIssue, ViewName, WhyLink, WhyResult, Written };

package/dist/cli.js

@@ -1,3 +1,4 @@
 import { t as exitCodes } from "./exit-codes-0ultCqdS.js";
-import { A as add, B as failureOf, C as blocked, D as path, E as impactOf, F as setState, I as findRun, L as loadRun, M as factsOf, N as setArtefact, O as ready, P as setFact, R as runFacts, S as swimlaneToMermaid, T as handoffsOf, _ as stateMachineToDot, a as defaultModelId, b as sequenceToMermaid, c as validateStored, d as formatNames, f as project, g as sequenceToDot, h as flowchartToDot, i as runProcess, j as artefactStates, k as why, l as sync, m as viewNames, n as nodePorts, o as runCli, p as show, r as packageVersion, s as validateDocument, t as defaultDataPath, u as emit, v as swimlaneToDot, w as cycles, x as stateMachineToMermaid, y as flowchartToMermaid, z as CliError } from "./dist-BxHnxpcT.js";
-export { CliError, add, artefactStates, blocked, cycles, defaultDataPath, defaultModelId, emit, exitCodes, factsOf, failureOf, findRun, flowchartToDot, flowchartToMermaid, formatNames, handoffsOf, impactOf, loadRun, nodePorts, packageVersion, path, project, ready, runCli, runFacts, runProcess, sequenceToDot, sequenceToMermaid, setArtefact, setFact, setState, show, stateMachineToDot, stateMachineToMermaid, swimlaneToDot, swimlaneToMermaid, sync, validateDocument, validateStored, viewNames, why };
+import { A as why, B as CliError, C as swimlaneToMermaid, D as impactOf, E as handoffsOf, F as setFact, I as setState, L as findRun, M as artefactStates, N as factsOf, O as path, P as setArtefact, R as loadRun, S as stateMachineToMermaid, T as cycles, V as failureOf, _ as sequenceToDot, a as defaultModelId, b as flowchartToMermaid, c as validateStored, d as emit, f as formatNames, g as flowchartToDot, h as viewNames, i as runProcess, j as add, k as ready, l as SyncInterruptedError, m as show, n as nodePorts, o as runCli, p as project, r as packageVersion, s as validateDocument, t as defaultDataPath, u as sync, v as stateMachineToDot, w as blocked, x as sequenceToMermaid, y as swimlaneToDot, z as runFacts } from "./dist-BI01yxFA.js";
+import { t as version } from "./version-Dagrkvwt.js";
+export { CliError, SyncInterruptedError, add, artefactStates, blocked, cycles, defaultDataPath, defaultModelId, emit, exitCodes, factsOf, failureOf, findRun, flowchartToDot, flowchartToMermaid, formatNames, handoffsOf, impactOf, loadRun, nodePorts, packageVersion, path, project, ready, runCli, runFacts, runProcess, sequenceToDot, sequenceToMermaid, setArtefact, setFact, setState, show, stateMachineToDot, stateMachineToMermaid, swimlaneToDot, swimlaneToMermaid, sync, validateDocument, validateStored, version, viewNames, why };

package/dist/data-file-BVMxkTug.js

@@ -0,0 +1,95 @@
+import { t as createSqliteGraphStore } from "./store-DKzvLGgl.js";
+import { sql } from "drizzle-orm";
+import { DatabaseSync } from "node:sqlite";
+import { drizzle } from "drizzle-orm/node-sqlite";
+import { chmodSync, closeSync, mkdirSync, openSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+//#region ../../adapters/graph/sqlite-node/dist/open.js
+/** The path `node:sqlite` reads as a private database in memory rather than a file. */
+const inMemory = ":memory:";
+/**
+* Opens a graph store on a SQLite database file, creating the file when it does not exist. The schema is migrated on the store's first operation.
+*
+* A file database is switched to write-ahead logging, so readers in other processes (a command line beside a server) are not blocked by a writer. Each process's change feed sees only its own writes.
+* @param path - The database file, or `":memory:"` for a private database that lives as long as the store.
+* @param options - `node:sqlite` options passed through unchanged, such as `timeout` for how long a write waits for another process's lock.
+* @returns The store, its database and a way to close it.
+*/
+const openNodeGraphStore = (path, options = {}) => {
+	const client = new DatabaseSync(path, options);
+	const db = drizzle({ client });
+	if (path !== inMemory) db.run(sql`PRAGMA journal_mode = WAL`);
+	return {
+		store: createSqliteGraphStore({ db }),
+		db,
+		close: () => {
+			client.close();
+		}
+	};
+};
+//#endregion
+//#region ../../adapters/graph/sqlite-node/dist/data-file.js
+/** The data directory's mode: only its owner may list or enter it, since the store holds synced work (titles, relationships) that other users on the host must not read. */
+const privateDirectoryMode = 448;
+/** The data file's mode: only its owner may read or write it. SQLite creates the `-wal` and `-shm` files beside it with the same mode on Unix. */
+const privateFileMode = 384;
+/** The permission bits of a file mode, without its type. */
+const permissionBits = 511;
+/** The bits that give the file's group or anyone else any access. */
+const groupAndOtherBits = 63;
+/** The SQLite files a store at `path` uses: the database and its write-ahead log and shared-memory index. */
+const storeFiles = (path) => [
+	path,
+	`${path}-wal`,
+	`${path}-shm`
+];
+/** Whether an error is the file system's report that a path does not exist, or already does. */
+const hasCode = (error, code) => error instanceof Error && "code" in error && error.code === code;
+/**
+* Narrows a path's mode to `mode` when its group or others have any access.
+* @param path - The path.
+* @param mode - The private mode it should have.
+* @returns Whether the mode was changed; `false` too when the path does not exist.
+*/
+const tighten = (path, mode) => {
+	let current;
+	try {
+		current = statSync(path).mode & permissionBits;
+	} catch (error) {
+		if (hasCode(error, "ENOENT")) return false;
+		throw error;
+	}
+	if ((current & groupAndOtherBits) === 0) return false;
+	chmodSync(path, mode);
+	return true;
+};
+/**
+* Makes a data file ready for `openNodeGraphStore` to open, so a store holding synced work is never readable by other users on the host. Call it before opening the store; it does not open the database itself.
+*
+* The directory is created when missing (with any missing parents), with `privateDirectoryMode` when it is the caller's own. The database file is created with `privateFileMode` when missing, before SQLite opens it, so the file and the `-wal` and `-shm` files SQLite derives from it are never readable by others, whatever the umask. A file that already exists is left alone unless the directory is the caller's own; there, an existing directory or store file (database, `-wal` or `-shm`) that group or others can read is narrowed to the private mode. On Windows, where file modes mean nothing, only the directory is created.
+* @param path - The database file; not `":memory:"`, which has no file.
+* @param options - Whether the caller owns the directory, and the platform.
+* @returns One warning line naming what was narrowed, for the caller to show, or nothing when nothing was.
+* @throws Error from the file system when the directory or file cannot be created or its mode read or changed.
+*/
+const prepareDataFile = (path, options) => {
+	const directory = dirname(path);
+	if (options.platform === "win32") {
+		mkdirSync(directory, { recursive: true });
+		return [];
+	}
+	mkdirSync(directory, options.ownsDirectory ? {
+		recursive: true,
+		mode: 448
+	} : { recursive: true });
+	try {
+		closeSync(openSync(path, "wx", 384));
+	} catch (error) {
+		if (!hasCode(error, "EEXIST")) throw error;
+	}
+	if (!options.ownsDirectory) return [];
+	const narrowed = [...tighten(directory, 448) ? [directory] : [], ...storeFiles(path).filter((file) => tighten(file, 384))];
+	return narrowed.length === 0 ? [] : [`made ${narrowed.join(", ")} readable by its owner only, since other users could read the synced work in it`];
+};
+//#endregion
+export { openNodeGraphStore as i, privateDirectoryMode as n, privateFileMode as r, prepareDataFile as t };

package/dist/dist-81kTKnMq.js

@@ -0,0 +1,3 @@
+import "./exit-codes-0ultCqdS.js";
+import { i as runProcess } from "./dist-BI01yxFA.js";
+export { runProcess };

package/dist/{dist-BxHnxpcT.js → dist-BI01yxFA.js}

@@ -1,20 +1,21 @@
-import { a as validateOverlay, d as overlayStatuses, f as participantKinds } from "./schema-CVnS6HiX.js";
+import { a as validateOverlay, d as overlayStatuses, f as participantKinds } from "./schema-BPT8fmfa.js";
 import { t as validate } from "./validate-DF3mQZww.js";
-import { n as parseModel, t as ModelParseError } from "./parse-CuipC_2K.js";
+import { n as parseModel, t as ModelParseError } from "./parse-C1Q1zsGt.js";
 import { c as deriveStatuses, f as toStateMachine, g as handoffs, h as toFlowchart, i as readySet, n as criticalPath, p as toSwimlane, r as impact, s as explainStatus, t as blockedBy, u as toSequence } from "./queries-C8kIDRiY.js";
 import { S as UnknownNodeError, f as layeredFacts, n as illegalCycles, u as factsFrom, x as CycleError } from "./control-DiygoEhm.js";
-import { l as assembleSync, t as createGitHubIssuesSource, u as createGraphSourceRouter } from "./source-DRDpEA8Q.js";
+import { l as assembleSync, t as createGitHubIssuesSource, u as createGraphSourceRouter } from "./source-D51N7K3A.js";
+import { t as GraphSourceError } from "./errors-BZe5WzCn.js";
 import { t as githubTokenFromEnvironment } from "./node-AchI1T-K.js";
-import { g as emptyModel } from "./store-BJILV4JS.js";
-import { t as createGraphStoreRouter } from "./router-DvGGLnNt.js";
-import { t as openNodeGraphStore } from "./open-BF-UHqeW.js";
+import { g as emptyModel } from "./store-DKzvLGgl.js";
+import { t as createGraphStoreRouter } from "./router-Dk91O_9p.js";
+import { i as openNodeGraphStore, t as prepareDataFile } from "./data-file-BVMxkTug.js";
 import { t as exitCodes } from "./exit-codes-0ultCqdS.js";
 import { ORPCError, createRouterClient } from "@orpc/server";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { Argument, Command, CommanderError, Option } from "commander";
-import { chmodSync, closeSync, mkdirSync, openSync, readFileSync, statSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
 //#region ../graph-cli/dist/errors.js
 /** A failure the command line reports with its own exit status and message, and nothing else. */
 var CliError = class extends Error {
@@ -46,6 +47,16 @@ const issueLines = (data) => {
 	return data.issues.flatMap((issue) => typeof issue === "object" && issue !== null && "code" in issue && "message" in issue && typeof issue.code === "string" && typeof issue.message === "string" ? [`${issue.code}: ${issue.message}`] : []);
 };
 /**
+* The error underneath a source's failure, for a failure's cause. A source called in process through oRPC fails with an `ORPCError` whose cause is the `GraphSourceError` the source threw, whose own cause, when it has one, is what went wrong underneath, such as a token port's error. Those two layers say nothing more than the failure's message and exit status already do, so the innermost error is the one worth keeping.
+* @param error - What the source call threw.
+* @returns The `GraphSourceError`'s cause when it has one, otherwise that `GraphSourceError`; anything else as it is.
+*/
+const underlyingCause = (error) => {
+	const sourceError = error instanceof ORPCError && error.cause instanceof GraphSourceError ? error.cause : error;
+	if (!(sourceError instanceof GraphSourceError)) return error;
+	return sourceError.cause === void 0 ? sourceError : sourceError.cause;
+};
+/**
 * Classifies anything a command threw into its exit status and the message for standard error. A commander usage error has already printed its own message, so it is reported with an empty one.
 * @param error - What was thrown.
 * @returns The exit status and message.
@@ -471,6 +482,21 @@ const renderSetFact = (result) => lines([`set fact ${result.fact} to ${result.va
 const renderFacts = (result) => lines([...Object.entries(result.facts.artefacts).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([id, provided]) => `artefact\t${id}\t${provided ? "provided" : "absent"}`), ...Object.entries(result.facts.values).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([name, value]) => `fact\t${name}\t${valueText(value)}`)]);
 /** `sync`: what was written, then each gap as its reason, target and message. */
 const renderSync = (result) => lines([`synced ${String(result.activities)} activities, ${String(result.transitions)} transitions and ${String(result.participants)} participants into "${result.modelId}" at revision ${String(result.revision)}`, ...result.gaps.map((gap) => `gap\t${gap.reason}\t${gap.target}\t${gap.message}`)]);
+/**
+* A sync a source interrupted: the source's failure, whether the pages read before it were saved, and the commands that carry on, `resume with: sync <scopes> --after <cursor>` for the failing source and `then: sync <scopes>` for the sources not reached.
+* @param message - The source's failure.
+* @param interruption - Where the sync carries on.
+* @returns The lines for standard error, without a final line break.
+*/
+const renderSyncInterruption = (message, interruption) => {
+	const { resume, remaining, saved } = interruption;
+	return [
+		message,
+		...saved ? ["the pages read before the failure are saved"] : [],
+		`resume with: sync ${resume.scopes.join(" ")}${resume.after === void 0 ? "" : ` --after ${resume.after}`}`,
+		...remaining.length === 0 ? [] : [`then: sync ${remaining.join(" ")}`]
+	].join("\n");
+};
 /** `validate`: `valid`, or each issue as its code, its JSON pointer when it has one, and its message. */
 const renderValidate = (result) => result.valid ? lines(["valid"]) : lines(result.issues.map((issue) => issue.pointer === void 0 ? `${issue.code}\t${issue.message}` : `${issue.code}\t${issue.pointer === "" ? "/" : issue.pointer}\t${issue.message}`));
 //#endregion
@@ -882,6 +908,27 @@ const show = async (session, request) => {
 };
 //#endregion
 //#region ../graph-cli/dist/sync.js
+/**
+* Thrown by `sync` when a source fails part way. Its exit status and message are the source's failure, classified as `failureOf` classifies it; its cause is the error underneath that failure, such as the token port's own error; and what to run next is data, in `resume` and `remaining`, never text.
+*/
+var SyncInterruptedError = class extends CliError {
+	resume;
+	remaining;
+	saved;
+	/**
+	* @param exitCode - The exit status the source's failure maps to.
+	* @param message - The source's failure.
+	* @param interruption - Where the sync carries on.
+	* @param options - The underlying error, kept as the cause.
+	*/
+	constructor(exitCode, message, interruption, options) {
+		super(exitCode, message, options);
+		this.name = "SyncInterruptedError";
+		this.resume = interruption.resume;
+		this.remaining = interruption.remaining;
+		this.saved = interruption.saved;
+	}
+};
 const scopeSeparator = ":";
 /** Groups scopes by their source prefix, keeping the order in which each prefix first appears. */
 const bySource = (scopes) => {
@@ -917,12 +964,12 @@ const boundActivities = (pages) => {
 /**
 * Reads every page of the scopes from their sources and merges them into the session's model in one write, creating the model when the store has none. Records already in the model are replaced by identifier and the rest are kept, so syncing again refreshes what changed.
 *
-* When a source fails part way, the pages read before the failure are still written, and the error says how to resume: the failing source's scopes with `--after` and the cursor of its last page read.
+* When a source fails part way, the pages read before the failure are still written, and the error carries where to carry on: the request that resumes the failing source after the cursor of its last page read, and the scopes of the sources not reached.
 * @param session - The store and model.
 * @param sources - The source for each identifier prefix.
 * @param request - The scopes, and a cursor to resume after.
 * @returns What was written, and the gaps the sources reported.
-* @throws CliError with `usage` for a scope with no source prefix, a prefix no source serves, or `after` with scopes of more than one source; and with the source's failure, the resume command added, when a source refuses the sync.
+* @throws CliError with `usage` for a scope with no source prefix, a prefix no source serves, or `after` with scopes of more than one source; and SyncInterruptedError, with the source's failure and where to carry on, when a source fails part way.
 */
 const sync = async (session, sources, request) => {
 	const groups = bySource(request.scopes);
@@ -969,13 +1016,14 @@ const sync = async (session, sources, request) => {
 			const failure = failureOf(error);
 			const saved = pages.length > 0;
 			if (saved) await write();
-			const later = clients.slice(index + 1).flatMap((next) => next.scopes);
-			throw new CliError(failure.exitCode, [
-				failure.message,
-				...saved ? ["the pages read before the failure are saved"] : [],
-				`resume with: sync ${group.scopes.join(" ")}${cursor === void 0 ? "" : ` --after ${cursor}`}`,
-				...later.length === 0 ? [] : [`then: sync ${later.join(" ")}`]
-			].join("\n"), { cause: error });
+			throw new SyncInterruptedError(failure.exitCode, failure.message, {
+				resume: cursor === void 0 ? { scopes: group.scopes } : {
+					scopes: group.scopes,
+					after: cursor
+				},
+				remaining: clients.slice(index + 1).flatMap((next) => next.scopes),
+				saved
+			}, { cause: underlyingCause(error) });
 		}
 		await readFrom(index + 1);
 	};
@@ -1137,14 +1185,19 @@ const runCli = async (args, ports, identity) => {
 	program.command("sync").description("read the scopes from their sources and merge them into the model").argument("<scope...>", "source-qualified scopes, such as github:owner or github:owner/repo").option("--after <cursor>", "resume an interrupted sync after this cursor").action(async (scopes, options, command) => {
 		const { after } = options;
 		await withSession(async (session) => {
-			const result = await sync(session, ports.source, typeof after === "string" ? {
-				scopes,
-				after
-			} : { scopes });
-			return {
-				json: result,
-				text: renderSync(result)
-			};
+			try {
+				const result = await sync(session, ports.source, typeof after === "string" ? {
+					scopes,
+					after
+				} : { scopes });
+				return {
+					json: result,
+					text: renderSync(result)
+				};
+			} catch (error) {
+				if (error instanceof SyncInterruptedError) throw new CliError(error.exitCode, renderSyncInterruption(error.message, error), { cause: error });
+				throw error;
+			}
 		})(command);
 	});
 	program.command("ready").description("list the work that can start now").action(async (_options, command) => {
@@ -1388,61 +1441,6 @@ const runCli = async (args, ports, identity) => {
 	}
 	return exitCode;
 };
-/** The permission bits of a file mode, without its type. */
-const permissionBits = 511;
-/** The bits that give the file's group or anyone else any access. */
-const groupAndOtherBits = 63;
-/** The SQLite files a store at `path` uses: the database and its write-ahead log and shared-memory index. */
-const storeFiles = (path) => [
-	path,
-	`${path}-wal`,
-	`${path}-shm`
-];
-/** Whether an error is the file system's report that a path does not exist, or already does. */
-const hasCode = (error, code) => error instanceof Error && "code" in error && error.code === code;
-/**
-* Narrows a path's mode to `mode` when its group or others have any access.
-* @param path - The path.
-* @param mode - The private mode it should have.
-* @returns Whether the mode was changed; `false` too when the path does not exist.
-*/
-const tighten = (path, mode) => {
-	let current;
-	try {
-		current = statSync(path).mode & permissionBits;
-	} catch (error) {
-		if (hasCode(error, "ENOENT")) return false;
-		throw error;
-	}
-	if ((current & groupAndOtherBits) === 0) return false;
-	chmodSync(path, mode);
-	return true;
-};
-/**
-* Makes a data file ready for SQLite to open. The directory is created when missing, private when it is the command line's own. The database file is created private when missing, before SQLite opens it, so the file and the sidecars SQLite derives from it are never readable by others, whatever the umask; a file that already exists is left alone unless the directory is the command line's own. In its own directory, an existing directory or store file that group or others can read is narrowed to the private mode.
-* @param path - The database file.
-* @param options - How much of the path the command line owns, and the platform.
-* @returns One warning line naming what was narrowed, or nothing.
-*/
-const prepareDataFile = (path, options) => {
-	const directory = dirname(path);
-	if (options.platform === "win32") {
-		mkdirSync(directory, { recursive: true });
-		return [];
-	}
-	mkdirSync(directory, options.ownsDirectory ? {
-		recursive: true,
-		mode: 448
-	} : { recursive: true });
-	try {
-		closeSync(openSync(path, "wx", 384));
-	} catch (error) {
-		if (!hasCode(error, "EEXIST")) throw error;
-	}
-	if (!options.ownsDirectory) return [];
-	const narrowed = [...tighten(directory, 448) ? [directory] : [], ...storeFiles(path).filter((file) => tighten(file, 384))];
-	return narrowed.length === 0 ? [] : [`made ${narrowed.join(", ")} readable by its owner only, since other users could read the synced work in it`];
-};
 //#endregion
 //#region ../graph-cli/dist/node.js
 /** The variable that names the data file outright. */
@@ -1485,7 +1483,7 @@ const packageVersion = (manifest) => {
 	return parsed.version;
 };
 /**
-* The ports for a Node process: the SQLite store over `node:sqlite` (creating the data file's directory when needed), the GitHub issues source for `github:` scopes, the file system and the process's streams.
+* The ports for a Node process: the SQLite store over `node:sqlite` (creating the data file's directory when needed, private when the command line or the host owns it), the GitHub issues source for `github:` scopes, the file system and the process's streams.
 * @param options - Replacements for any of the defaults.
 * @returns The ports.
 */
@@ -1493,7 +1491,7 @@ const nodePorts = (options = {}) => {
 	const env = options.env ?? process.env;
 	const token = options.token ?? githubTokenFromEnvironment({ env });
 	const home = options.home ?? homedir();
-	const ownDataPath = xdgDataPath(env, home);
+	const ownDataPath = options.dataPath ?? xdgDataPath(env, home);
 	return {
 		stdout: options.stdout ?? ((text) => {
 			process.stdout.write(text);
@@ -1501,7 +1499,7 @@ const nodePorts = (options = {}) => {
 		stderr: options.stderr ?? ((text) => {
 			process.stderr.write(text);
 		}),
-		defaultDataPath: defaultDataPath(env, home),
+		defaultDataPath: options.dataPath ?? defaultDataPath(env, home),
 		openStore: (path) => {
 			const warnings = path === inMemory ? [] : prepareDataFile(path, {
 				ownsDirectory: path === ownDataPath,
@@ -1540,4 +1538,4 @@ const runProcess = async (identity) => {
 	return runCli(process.argv.slice(2), nodePorts({ signal: controller.signal }), identity);
 };
 //#endregion
-export { add as A, failureOf as B, blocked as C, path as D, impactOf as E, setState as F, findRun as I, loadRun as L, factsOf as M, setArtefact as N, ready as O, setFact as P, runFacts as R, swimlaneToMermaid as S, handoffsOf as T, stateMachineToDot as _, defaultModelId as a, sequenceToMermaid as b, validateStored as c, formatNames as d, project as f, sequenceToDot as g, flowchartToDot as h, runProcess as i, artefactStates as j, why as k, sync as l, viewNames as m, nodePorts as n, runCli as o, show as p, packageVersion as r, validateDocument as s, defaultDataPath as t, emit as u, swimlaneToDot as v, cycles as w, stateMachineToMermaid as x, flowchartToMermaid as y, CliError as z };
+export { why as A, CliError as B, swimlaneToMermaid as C, impactOf as D, handoffsOf as E, setFact as F, setState as I, findRun as L, artefactStates as M, factsOf as N, path as O, setArtefact as P, loadRun as R, stateMachineToMermaid as S, cycles as T, failureOf as V, sequenceToDot as _, defaultModelId as a, flowchartToMermaid as b, validateStored as c, emit as d, formatNames as f, flowchartToDot as g, viewNames as h, runProcess as i, add as j, ready as k, SyncInterruptedError as l, show as m, nodePorts as n, runCli as o, project as p, packageVersion as r, validateDocument as s, defaultDataPath as t, sync as u, stateMachineToDot as v, blocked as w, sequenceToMermaid as x, swimlaneToDot as y, runFacts as z };