@graphorin/cli 0.5.0

package/dist/commands/secrets.js

@@ -0,0 +1,182 @@
+import { brand, defaultPrintSink, emitReport, statusMarker } from "../internal/output.js";
+import { EXIT_CODES } from "../internal/exit.js";
+import { stdin } from "node:process";
+import { SecretValue, createSecretsStore, getActiveSecretsStore, parseSecretRef, resolveSecret } from "@graphorin/security";
+
+//#region src/commands/secrets.ts
+/**
+* `graphorin secrets` — manage the operator's secrets store.
+*
+* Surface (per Phase 15 § Secrets):
+*
+*  - `graphorin secrets list`
+*  - `graphorin secrets get <key>`
+*  - `graphorin secrets set <key> [--value <v>] [--from-stdin] [--scope <ref>]`
+*  - `graphorin secrets delete <key>`
+*  - `graphorin secrets ref <uri>` — test resolution of a `SecretRef` URI.
+*  - `graphorin secrets rotate <key> --new-value <v>`
+*
+* Honours `--secrets-source <kind>` and `--strict-secrets` per
+* DEC-136 — both flags are forwarded to `createSecretsStore(...)` so
+* the CLI activates the same store the running server would.
+*
+* The CLI never logs raw secret bytes. `get` prints the value through
+* `value.use((s) => print(s))` so the bytes are released as soon as
+* the print callback returns; `--json` mode emits only the metadata
+* fields, never the value, unless `--reveal` is explicitly supplied.
+*
+* @packageDocumentation
+*/
+/** @stable */
+async function runSecretsList(options = {}) {
+	const list = await (await openStore(options)).list();
+	emitReport(options, list, () => {
+		const print = options.print ?? defaultPrintSink;
+		if (list.length === 0) {
+			print(brand("no secrets recorded."));
+			return;
+		}
+		print(brand(`${list.length} secret(s):`));
+		for (const m of list) print(`  ${statusMarker("ok")} ${m.key} (updated=${m.updatedAt ?? "-"})`);
+	});
+	return list;
+}
+/** @stable */
+async function runSecretsGet(options) {
+	const value = await (await openStore(options)).get(options.key);
+	if (value === null) {
+		const out$1 = Object.freeze({
+			key: options.key,
+			found: false
+		});
+		emitReport(options, out$1, () => {
+			(options.print ?? defaultPrintSink)(brand(`secret '${options.key}' not found.`));
+			process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;
+		});
+		return out$1;
+	}
+	if (options.reveal === true) {
+		const raw = await value.use((s) => String(s));
+		const out$1 = Object.freeze({
+			key: options.key,
+			found: true,
+			value: raw
+		});
+		emitReport(options, out$1, () => {
+			const print = options.print ?? defaultPrintSink;
+			print(brand(`secret '${options.key}' resolved (length=${raw.length})`));
+			print(`  ${raw}`);
+		});
+		return out$1;
+	}
+	const out = Object.freeze({
+		key: options.key,
+		found: true
+	});
+	emitReport(options, out, () => {
+		(options.print ?? defaultPrintSink)(brand(`secret '${options.key}' found (use --reveal to print the bytes)`));
+	});
+	return out;
+}
+/** @stable */
+async function runSecretsSet(options) {
+	const store = await openStore(options);
+	let raw = options.value;
+	if (raw === void 0 && options.fromStdin === true) raw = await readStdin();
+	if (raw === void 0) throw new Error("[graphorin/cli] secrets set requires either --value <v> or --from-stdin (no plaintext on the command line).");
+	await store.set(options.key, SecretValue.fromString(raw, { source: { resolver: "graphorin secrets set" } }));
+	emitReport(options, { ok: true }, () => {
+		(options.print ?? defaultPrintSink)(brand(`secret '${options.key}' written.`));
+	});
+	return { ok: true };
+}
+/** @stable */
+async function runSecretsDelete(options) {
+	await (await openStore(options)).delete(options.key);
+	emitReport(options, { ok: true }, () => {
+		(options.print ?? defaultPrintSink)(brand(`secret '${options.key}' deleted.`));
+	});
+	return { ok: true };
+}
+/**
+* Test resolution of a `SecretRef` URI. The CLI parses the URI first
+* (sanity check + scheme echo), then resolves through the registered
+* resolver chain.
+*
+* @stable
+*/
+async function runSecretsRef(options) {
+	const parsed = parseSecretRef(options.uri);
+	try {
+		const value = await resolveSecret(options.uri);
+		const length = await value.use((s) => s.length);
+		const raw = options.reveal === true ? await value.use((s) => String(s)) : void 0;
+		const out = Object.freeze({
+			uri: options.uri,
+			scheme: parsed.scheme,
+			resolved: true,
+			length,
+			...raw !== void 0 ? { value: raw } : {}
+		});
+		emitReport(options, out, () => {
+			(options.print ?? defaultPrintSink)(brand(`${statusMarker("ok")} resolved '${parsed.scheme}' ref (length=${length}${raw !== void 0 ? `, value='${raw}'` : ""})`));
+		});
+		return out;
+	} catch (err) {
+		const out = Object.freeze({
+			uri: options.uri,
+			scheme: parsed.scheme,
+			resolved: false
+		});
+		emitReport(options, out, () => {
+			(options.print ?? defaultPrintSink)(brand(`${statusMarker("fail")} ${parsed.scheme} ref failed: ${err.message}`));
+			process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;
+		});
+		return out;
+	}
+}
+/**
+* `graphorin secrets rotate <key>` — overwrite the existing value
+* with a fresh one. Functionally identical to `set` but the CLI
+* surfaces the operation explicitly so audit logs can distinguish
+* a rotation from an initial write.
+*
+* @stable
+*/
+async function runSecretsRotate(options) {
+	const store = await openStore(options);
+	if (await store.get(options.key) === null) throw new Error(`[graphorin/cli] cannot rotate '${options.key}' — secret does not exist (use 'graphorin secrets set' to create it).`);
+	let raw = options.newValue;
+	if (raw === void 0 && options.fromStdin === true) raw = await readStdin();
+	if (raw === void 0) throw new Error("[graphorin/cli] secrets rotate requires either --new-value <v> or --from-stdin.");
+	await store.set(options.key, SecretValue.fromString(raw, { source: { resolver: "graphorin secrets rotate" } }));
+	emitReport(options, { ok: true }, () => {
+		(options.print ?? defaultPrintSink)(brand(`secret '${options.key}' rotated.`));
+	});
+	return { ok: true };
+}
+async function openStore(options) {
+	if (options.secretsSource === void 0) {
+		const active = getActiveSecretsStore();
+		if (active !== void 0) return active;
+	}
+	return await createSecretsStore({
+		...options.secretsSource !== void 0 ? { kind: options.secretsSource } : {},
+		...options.strictSecrets !== void 0 ? { strict: options.strictSecrets } : {}
+	});
+}
+async function readStdin() {
+	return await new Promise((resolve, reject) => {
+		let buf = "";
+		stdin.setEncoding("utf8");
+		stdin.on("data", (chunk) => {
+			buf += chunk;
+		});
+		stdin.on("end", () => resolve(buf.replace(/\r?\n$/, "")));
+		stdin.on("error", reject);
+	});
+}
+
+//#endregion
+export { runSecretsDelete, runSecretsGet, runSecretsList, runSecretsRef, runSecretsRotate, runSecretsSet };
+//# sourceMappingURL=secrets.js.map

package/dist/commands/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","names":["out: SecretsGetResult","out","out: SecretsRefResult"],"sources":["../../src/commands/secrets.ts"],"sourcesContent":["/**\n * `graphorin secrets` — manage the operator's secrets store.\n *\n * Surface (per Phase 15 § Secrets):\n *\n *  - `graphorin secrets list`\n *  - `graphorin secrets get <key>`\n *  - `graphorin secrets set <key> [--value <v>] [--from-stdin] [--scope <ref>]`\n *  - `graphorin secrets delete <key>`\n *  - `graphorin secrets ref <uri>` — test resolution of a `SecretRef` URI.\n *  - `graphorin secrets rotate <key> --new-value <v>`\n *\n * Honours `--secrets-source <kind>` and `--strict-secrets` per\n * DEC-136 — both flags are forwarded to `createSecretsStore(...)` so\n * the CLI activates the same store the running server would.\n *\n * The CLI never logs raw secret bytes. `get` prints the value through\n * `value.use((s) => print(s))` so the bytes are released as soon as\n * the print callback returns; `--json` mode emits only the metadata\n * fields, never the value, unless `--reveal` is explicitly supplied.\n *\n * @packageDocumentation\n */\n\nimport { stdin } from 'node:process';\n\nimport type { SecretMetadata } from '@graphorin/core/contracts';\nimport {\n  createSecretsStore,\n  getActiveSecretsStore,\n  parseSecretRef,\n  resolveSecret,\n  type SecretsStoreKind,\n  SecretValue,\n} from '@graphorin/security';\n\nimport { EXIT_CODES } from '../internal/exit.js';\nimport {\n  brand,\n  type CommonOutputOptions,\n  defaultPrintSink,\n  emitReport,\n  statusMarker,\n} from '../internal/output.js';\n\n/** @stable */\nexport interface SecretsCommonOptions extends CommonOutputOptions {\n  /** Mirrors `--secrets-source` per DEC-136. */\n  readonly secretsSource?: SecretsStoreKind;\n  /** Mirrors `--strict-secrets` per DEC-136. */\n  readonly strictSecrets?: boolean;\n}\n\n/** @stable */\nexport interface SecretsListOptions extends SecretsCommonOptions {}\n\n/** @stable */\nexport async function runSecretsList(\n  options: SecretsListOptions = {},\n): Promise<ReadonlyArray<SecretMetadata>> {\n  const store = await openStore(options);\n  const list = await store.list();\n  emitReport(options, list, () => {\n    const print = options.print ?? defaultPrintSink;\n    if (list.length === 0) {\n      print(brand('no secrets recorded.'));\n      return;\n    }\n    print(brand(`${list.length} secret(s):`));\n    for (const m of list) {\n      print(`  ${statusMarker('ok')} ${m.key} (updated=${m.updatedAt ?? '-'})`);\n    }\n  });\n  return list;\n}\n\n/** @stable */\nexport interface SecretsGetOptions extends SecretsCommonOptions {\n  readonly key: string;\n  /**\n   * When `true`, print the raw value through the human report. The\n   * default is to print only structured metadata so the bytes do not\n   * surface in shell history.\n   */\n  readonly reveal?: boolean;\n}\n\n/** @stable */\nexport interface SecretsGetResult {\n  readonly key: string;\n  readonly found: boolean;\n  /** Only present when `reveal: true` AND the secret exists. */\n  readonly value?: string;\n}\n\n/** @stable */\nexport async function runSecretsGet(options: SecretsGetOptions): Promise<SecretsGetResult> {\n  const store = await openStore(options);\n  const value = await store.get(options.key);\n  if (value === null) {\n    const out: SecretsGetResult = Object.freeze({ key: options.key, found: false });\n    emitReport(options, out, () => {\n      const print = options.print ?? defaultPrintSink;\n      print(brand(`secret '${options.key}' not found.`));\n      process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;\n    });\n    return out;\n  }\n  if (options.reveal === true) {\n    const raw = await value.use((s) => String(s));\n    const out: SecretsGetResult = Object.freeze({ key: options.key, found: true, value: raw });\n    emitReport(options, out, () => {\n      const print = options.print ?? defaultPrintSink;\n      print(brand(`secret '${options.key}' resolved (length=${raw.length})`));\n      print(`  ${raw}`);\n    });\n    return out;\n  }\n  const out: SecretsGetResult = Object.freeze({ key: options.key, found: true });\n  emitReport(options, out, () => {\n    const print = options.print ?? defaultPrintSink;\n    print(brand(`secret '${options.key}' found (use --reveal to print the bytes)`));\n  });\n  return out;\n}\n\n/** @stable */\nexport interface SecretsSetOptions extends SecretsCommonOptions {\n  readonly key: string;\n  readonly value?: string;\n  /** When `true`, read the value from stdin. */\n  readonly fromStdin?: boolean;\n}\n\n/** @stable */\nexport async function runSecretsSet(options: SecretsSetOptions): Promise<{ readonly ok: true }> {\n  const store = await openStore(options);\n  let raw = options.value;\n  if (raw === undefined && options.fromStdin === true) {\n    raw = await readStdin();\n  }\n  if (raw === undefined) {\n    throw new Error(\n      '[graphorin/cli] secrets set requires either --value <v> or --from-stdin (no plaintext on the command line).',\n    );\n  }\n  await store.set(\n    options.key,\n    SecretValue.fromString(raw, { source: { resolver: 'graphorin secrets set' } }),\n  );\n  emitReport(options, { ok: true } as const, () => {\n    const print = options.print ?? defaultPrintSink;\n    print(brand(`secret '${options.key}' written.`));\n  });\n  return { ok: true };\n}\n\n/** @stable */\nexport interface SecretsDeleteOptions extends SecretsCommonOptions {\n  readonly key: string;\n}\n\n/** @stable */\nexport async function runSecretsDelete(\n  options: SecretsDeleteOptions,\n): Promise<{ readonly ok: true }> {\n  const store = await openStore(options);\n  await store.delete(options.key);\n  emitReport(options, { ok: true } as const, () => {\n    const print = options.print ?? defaultPrintSink;\n    print(brand(`secret '${options.key}' deleted.`));\n  });\n  return { ok: true };\n}\n\n/** @stable */\nexport interface SecretsRefOptions extends CommonOutputOptions {\n  readonly uri: string;\n  readonly reveal?: boolean;\n}\n\n/** @stable */\nexport interface SecretsRefResult {\n  readonly uri: string;\n  readonly scheme: string;\n  readonly resolved: boolean;\n  readonly length?: number;\n  readonly value?: string;\n}\n\n/**\n * Test resolution of a `SecretRef` URI. The CLI parses the URI first\n * (sanity check + scheme echo), then resolves through the registered\n * resolver chain.\n *\n * @stable\n */\nexport async function runSecretsRef(options: SecretsRefOptions): Promise<SecretsRefResult> {\n  const parsed = parseSecretRef(options.uri);\n  try {\n    const value = await resolveSecret(options.uri);\n    const length = await value.use((s) => s.length);\n    const raw = options.reveal === true ? await value.use((s) => String(s)) : undefined;\n    const out: SecretsRefResult = Object.freeze({\n      uri: options.uri,\n      scheme: parsed.scheme,\n      resolved: true,\n      length,\n      ...(raw !== undefined ? { value: raw } : {}),\n    });\n    emitReport(options, out, () => {\n      const print = options.print ?? defaultPrintSink;\n      print(\n        brand(\n          `${statusMarker('ok')} resolved '${parsed.scheme}' ref (length=${length}${raw !== undefined ? `, value='${raw}'` : ''})`,\n        ),\n      );\n    });\n    return out;\n  } catch (err) {\n    const out: SecretsRefResult = Object.freeze({\n      uri: options.uri,\n      scheme: parsed.scheme,\n      resolved: false,\n    });\n    emitReport(options, out, () => {\n      const print = options.print ?? defaultPrintSink;\n      print(\n        brand(`${statusMarker('fail')} ${parsed.scheme} ref failed: ${(err as Error).message}`),\n      );\n      process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;\n    });\n    return out;\n  }\n}\n\n/** @stable */\nexport interface SecretsRotateOptions extends SecretsCommonOptions {\n  readonly key: string;\n  readonly newValue?: string;\n  readonly fromStdin?: boolean;\n}\n\n/**\n * `graphorin secrets rotate <key>` — overwrite the existing value\n * with a fresh one. Functionally identical to `set` but the CLI\n * surfaces the operation explicitly so audit logs can distinguish\n * a rotation from an initial write.\n *\n * @stable\n */\nexport async function runSecretsRotate(\n  options: SecretsRotateOptions,\n): Promise<{ readonly ok: true }> {\n  const store = await openStore(options);\n  const existing = await store.get(options.key);\n  if (existing === null) {\n    throw new Error(\n      `[graphorin/cli] cannot rotate '${options.key}' — secret does not exist (use 'graphorin secrets set' to create it).`,\n    );\n  }\n  let raw = options.newValue;\n  if (raw === undefined && options.fromStdin === true) raw = await readStdin();\n  if (raw === undefined) {\n    throw new Error(\n      '[graphorin/cli] secrets rotate requires either --new-value <v> or --from-stdin.',\n    );\n  }\n  await store.set(\n    options.key,\n    SecretValue.fromString(raw, { source: { resolver: 'graphorin secrets rotate' } }),\n  );\n  emitReport(options, { ok: true } as const, () => {\n    const print = options.print ?? defaultPrintSink;\n    print(brand(`secret '${options.key}' rotated.`));\n  });\n  return { ok: true };\n}\n\nasync function openStore(options: SecretsCommonOptions) {\n  // Reuse the per-process active store when the caller did not request\n  // a different kind. The singleton matches the running server / lib\n  // process so consecutive CLI invocations within the same process\n  // address the same backing store (this matters for the in-memory\n  // store + for subprocess CLI flows that share a parent's resolver\n  // chain via env vars).\n  if (options.secretsSource === undefined) {\n    const active = getActiveSecretsStore();\n    if (active !== undefined) return active;\n  }\n  return await createSecretsStore({\n    ...(options.secretsSource !== undefined ? { kind: options.secretsSource } : {}),\n    ...(options.strictSecrets !== undefined ? { strict: options.strictSecrets } : {}),\n  });\n}\n\nasync function readStdin(): Promise<string> {\n  return await new Promise((resolve, reject) => {\n    let buf = '';\n    stdin.setEncoding('utf8');\n    stdin.on('data', (chunk) => {\n      buf += chunk;\n    });\n    stdin.on('end', () => resolve(buf.replace(/\\r?\\n$/, '')));\n    stdin.on('error', reject);\n  });\n}\n"],"mappings":"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"}

package/dist/commands/skills.d.ts

@@ -0,0 +1,58 @@
+import { CommonOutputOptions } from "../internal/output.js";
+import { SkillInstallationStatus } from "@graphorin/security";
+import { MigrationResult } from "@graphorin/skills";
+
+//#region src/commands/skills.d.ts
+
+/** @stable */
+interface SkillsCommonOptions extends CommonOutputOptions {}
+/** @stable */
+type SkillTrustLevelInput = 'trusted' | 'trusted-with-scripts' | 'untrusted';
+/** @stable */
+interface SkillsInstallOptions extends SkillsCommonOptions {
+  /** `npm:<name>[@version]` or `git:<url>` source. */
+  readonly source: string;
+  /** Optional explicit version pin (npm sources only). */
+  readonly version?: string;
+  /** Optional git ref (git sources only). */
+  readonly ref?: string;
+  /** Trust level for the operator's project. Defaults to the helper's own default. */
+  readonly trustLevel?: SkillTrustLevelInput;
+  /** Working directory for npm installs. */
+  readonly cwd?: string;
+  readonly dryRun?: boolean;
+}
+/** @stable */
+declare function runSkillsInstall(options: SkillsInstallOptions): Promise<SkillInstallationStatus>;
+/** @stable */
+interface SkillsInspectOptions extends SkillsCommonOptions {
+  readonly name: string;
+}
+/** @stable */
+declare function runSkillsInspect(options: SkillsInspectOptions): Promise<SkillInstallationStatus | null>;
+/** @stable */
+interface SkillsAuditOptions extends SkillsCommonOptions {}
+/** @stable */
+declare function runSkillsAudit(options?: SkillsAuditOptions): readonly SkillInstallationStatus[];
+/** @stable */
+interface SkillsMigrateFrontmatterOptions extends SkillsCommonOptions {
+  /** Directory to walk. Defaults to `process.cwd()`. */
+  readonly path?: string;
+  readonly recursive?: boolean;
+  readonly apply?: boolean;
+}
+/** @stable */
+interface SkillsMigrateFrontmatterResult {
+  readonly directory: string;
+  readonly visited: number;
+  readonly migrated: ReadonlyArray<{
+    readonly file: string;
+    readonly result: MigrationResult;
+  }>;
+  readonly applied: boolean;
+}
+/** @stable */
+declare function runSkillsMigrateFrontmatter(options?: SkillsMigrateFrontmatterOptions): Promise<SkillsMigrateFrontmatterResult>;
+//#endregion
+export { SkillTrustLevelInput, SkillsAuditOptions, SkillsCommonOptions, SkillsInspectOptions, SkillsInstallOptions, SkillsMigrateFrontmatterOptions, SkillsMigrateFrontmatterResult, runSkillsAudit, runSkillsInspect, runSkillsInstall, runSkillsMigrateFrontmatter };
+//# sourceMappingURL=skills.d.ts.map

package/dist/commands/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","names":[],"sources":["../../src/commands/skills.ts"],"sourcesContent":[],"mappings":";;;;;;AA4KA;AAWsB,UA1IL,mBAAA,SAA4B,mBA0II,CAAA;;AAE9C,KAzIS,oBAAA,GAyIT,SAAA,GAAA,sBAAA,GAAA,WAAA;;UAtIc,oBAAA,SAA6B;;;;;;;;wBAQtB;;;;;;iBAOF,gBAAA,UACX,uBACR,QAAQ;;UA2CM,oBAAA,SAA6B;;;;iBAKxB,gBAAA,UACX,uBACR,QAAQ;;UAuBM,kBAAA,SAA2B;;iBAG5B,cAAA,WAAwB,8BAAuB;;UAoB9C,+BAAA,SAAwC;;;;;;;UAQxC,8BAAA;;;qBAGI;;qBAEA;;;;;iBAMC,2BAAA,WACX,kCACR,QAAQ"}

package/dist/commands/skills.js

@@ -0,0 +1,181 @@
+import { brand, defaultPrintSink, emitReport, statusMarker } from "../internal/output.js";
+import { EXIT_CODES } from "../internal/exit.js";
+import { checkOfflineModeBlocked } from "../internal/offline.js";
+import { readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import process from "node:process";
+import { auditInstalledSkills, installSkillFromGit, installSkillFromNpm } from "@graphorin/security";
+import { migrateFrontmatter } from "@graphorin/skills";
+
+//#region src/commands/skills.ts
+/**
+* `graphorin skills` — install + audit + migrate operator-managed
+* skill packages.
+*
+* Surface (per Phase 15 § Skills):
+*
+*  - `graphorin skills install <source>` — `npm:` or `git:` source.
+*    Honours allowlist / denylist + signature verification (DEC-140 /
+*    ADR-034). Refuses when `GRAPHORIN_OFFLINE=1` is set.
+*  - `graphorin skills inspect <name>` — frontmatter + signature +
+*    supply-chain status of an installed skill.
+*  - `graphorin skills audit` — full audit of every recorded
+*    installation.
+*  - `graphorin skills migrate-frontmatter [--apply] [--recursive]`
+*    — DEC-156: rewrites legacy `graphorin-*` frontmatter fields onto
+*    their upstream equivalents.
+*
+* @packageDocumentation
+*/
+/** @stable */
+async function runSkillsInstall(options) {
+	if (!checkOfflineModeBlocked("skills install", { ...options.print !== void 0 ? { print: options.print } : {} })) process.exit(EXIT_CODES.RECOVERABLE_FAILURE);
+	const print = options.print ?? defaultPrintSink;
+	const parsed = parseSource(options.source);
+	let result;
+	if (parsed.kind === "npm") result = await installSkillFromNpm({
+		packageName: parsed.value,
+		...options.version !== void 0 ? { version: options.version } : {},
+		...options.trustLevel !== void 0 ? { trustLevel: options.trustLevel } : {},
+		...options.cwd !== void 0 ? { cwd: options.cwd } : {},
+		...options.dryRun !== void 0 ? { dryRun: options.dryRun } : {}
+	});
+	else result = await installSkillFromGit({
+		repoUrl: parsed.value,
+		...options.ref !== void 0 ? { ref: options.ref } : {},
+		...options.trustLevel !== void 0 ? { trustLevel: options.trustLevel } : {},
+		...options.dryRun !== void 0 ? { dryRun: options.dryRun } : {}
+	});
+	emitReport(options, result, () => {
+		print(brand(`installed skill '${result.id}' (${result.source.kind}, signatureVerified=${result.signatureVerified})`));
+		if (result.signature !== void 0) print(`  signature valid: ${result.signature.valid}`);
+	});
+	return result;
+}
+/** @stable */
+async function runSkillsInspect(options) {
+	const match = auditInstalledSkills().find((s) => s.id === options.name) ?? null;
+	emitReport(options, match, () => {
+		const print = options.print ?? defaultPrintSink;
+		if (match === null) {
+			print(brand(`skill '${options.name}' not found in this process registry.`));
+			process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;
+			return;
+		}
+		print(brand(`skill ${match.id}`));
+		print(`  source: ${match.source.kind}`);
+		print(`  trust level: ${match.trustLevel}`);
+		print(`  ignoreScripts: ${match.ignoreScripts}`);
+		print(`  signatureVerified: ${match.signatureVerified}`);
+		print(`  installedAt: ${new Date(match.installedAt).toISOString()}`);
+		if (match.installPath !== void 0) print(`  installPath: ${match.installPath}`);
+		if (match.publisher !== void 0) print(`  publisher: ${match.publisher}`);
+	});
+	return match;
+}
+/** @stable */
+function runSkillsAudit(options = {}) {
+	const all = auditInstalledSkills();
+	emitReport(options, all, () => {
+		const print = options.print ?? defaultPrintSink;
+		if (all.length === 0) {
+			print(brand("no skills installed in this process registry."));
+			return;
+		}
+		print(brand(`${all.length} installed skill(s):`));
+		for (const s of all) print(`  ${s.signatureVerified ? statusMarker("ok") : statusMarker("warn")} ${s.id} (${s.source.kind}, trust=${s.trustLevel}, signatureVerified=${s.signatureVerified})`);
+	});
+	return all;
+}
+/** @stable */
+async function runSkillsMigrateFrontmatter(options = {}) {
+	const root = resolve(options.path ?? process.cwd());
+	const recursive = options.recursive === true;
+	const apply = options.apply === true;
+	const files = await collectSkillMd(root, recursive);
+	const migrated = [];
+	for (const file of files) {
+		const raw = await readFile(file, "utf8");
+		let result;
+		try {
+			result = migrateFrontmatter(raw, {
+				apply,
+				skillId: file
+			});
+		} catch {
+			continue;
+		}
+		if (result.changed) {
+			if (apply) await writeFile(file, result.migratedSkillMd, { mode: 384 });
+			migrated.push({
+				file,
+				result
+			});
+		}
+	}
+	const out = Object.freeze({
+		directory: root,
+		visited: files.length,
+		migrated: Object.freeze(migrated),
+		applied: apply
+	});
+	emitReport(options, out, () => {
+		const print = options.print ?? defaultPrintSink;
+		print(brand(`migrate-frontmatter visited ${out.visited} SKILL.md file(s) under ${out.directory}.`));
+		if (out.migrated.length === 0) {
+			print(brand("no rewrites required."));
+			return;
+		}
+		print(brand(`${out.migrated.length} file(s) ${apply ? "rewritten" : "would be rewritten (dry-run)"}:`));
+		for (const m of out.migrated) print(`  - ${m.file}`);
+	});
+	return out;
+}
+function parseSource(input) {
+	if (input.startsWith("npm:")) return {
+		kind: "npm",
+		value: input.slice(4)
+	};
+	if (input.startsWith("git:")) return {
+		kind: "git",
+		value: input.slice(4)
+	};
+	if (input.includes("://")) return {
+		kind: "git",
+		value: input
+	};
+	return {
+		kind: "npm",
+		value: input
+	};
+}
+async function collectSkillMd(root, recursive) {
+	const out = [];
+	await walk(root, recursive, out);
+	return out;
+}
+async function walk(dir, recursive, acc) {
+	let entries;
+	try {
+		entries = await readdir(dir);
+	} catch {
+		return;
+	}
+	for (const name of entries) {
+		if (name === "node_modules" || name === ".git" || name === "dist") continue;
+		const full = join(dir, name);
+		let s;
+		try {
+			s = await stat(full);
+		} catch {
+			continue;
+		}
+		if (s.isDirectory()) {
+			if (recursive) await walk(full, recursive, acc);
+		} else if (name === "SKILL.md") acc.push(full);
+	}
+}
+
+//#endregion
+export { runSkillsAudit, runSkillsInspect, runSkillsInstall, runSkillsMigrateFrontmatter };
+//# sourceMappingURL=skills.js.map

package/dist/commands/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","names":["result: SkillInstallationStatus","migrated: Array<{ file: string; result: MigrationResult }>","result: MigrationResult","out: SkillsMigrateFrontmatterResult","out: string[]","entries: string[]","s: import('node:fs').Stats"],"sources":["../../src/commands/skills.ts"],"sourcesContent":["/**\n * `graphorin skills` — install + audit + migrate operator-managed\n * skill packages.\n *\n * Surface (per Phase 15 § Skills):\n *\n *  - `graphorin skills install <source>` — `npm:` or `git:` source.\n *    Honours allowlist / denylist + signature verification (DEC-140 /\n *    ADR-034). Refuses when `GRAPHORIN_OFFLINE=1` is set.\n *  - `graphorin skills inspect <name>` — frontmatter + signature +\n *    supply-chain status of an installed skill.\n *  - `graphorin skills audit` — full audit of every recorded\n *    installation.\n *  - `graphorin skills migrate-frontmatter [--apply] [--recursive]`\n *    — DEC-156: rewrites legacy `graphorin-*` frontmatter fields onto\n *    their upstream equivalents.\n *\n * @packageDocumentation\n */\n\nimport { readdir, readFile, stat, writeFile } from 'node:fs/promises';\nimport { join, resolve } from 'node:path';\nimport process from 'node:process';\n\nimport {\n  auditInstalledSkills,\n  type InstallSkillFromGitOptions,\n  type InstallSkillFromNpmOptions,\n  installSkillFromGit,\n  installSkillFromNpm,\n  type SkillInstallationStatus,\n} from '@graphorin/security';\nimport { loadSkills, type MigrationResult, migrateFrontmatter } from '@graphorin/skills';\n\nimport { EXIT_CODES } from '../internal/exit.js';\nimport { checkOfflineModeBlocked } from '../internal/offline.js';\nimport {\n  brand,\n  type CommonOutputOptions,\n  defaultPrintSink,\n  emitReport,\n  statusMarker,\n} from '../internal/output.js';\n\n/** @stable */\nexport interface SkillsCommonOptions extends CommonOutputOptions {}\n\n/** @stable */\nexport type SkillTrustLevelInput = 'trusted' | 'trusted-with-scripts' | 'untrusted';\n\n/** @stable */\nexport interface SkillsInstallOptions extends SkillsCommonOptions {\n  /** `npm:<name>[@version]` or `git:<url>` source. */\n  readonly source: string;\n  /** Optional explicit version pin (npm sources only). */\n  readonly version?: string;\n  /** Optional git ref (git sources only). */\n  readonly ref?: string;\n  /** Trust level for the operator's project. Defaults to the helper's own default. */\n  readonly trustLevel?: SkillTrustLevelInput;\n  /** Working directory for npm installs. */\n  readonly cwd?: string;\n  readonly dryRun?: boolean;\n}\n\n/** @stable */\nexport async function runSkillsInstall(\n  options: SkillsInstallOptions,\n): Promise<SkillInstallationStatus> {\n  if (\n    !checkOfflineModeBlocked('skills install', {\n      ...(options.print !== undefined ? { print: options.print } : {}),\n    })\n  ) {\n    process.exit(EXIT_CODES.RECOVERABLE_FAILURE);\n  }\n  const print = options.print ?? defaultPrintSink;\n  const parsed = parseSource(options.source);\n  let result: SkillInstallationStatus;\n  if (parsed.kind === 'npm') {\n    const installOpts: InstallSkillFromNpmOptions = {\n      packageName: parsed.value,\n      ...(options.version !== undefined ? { version: options.version } : {}),\n      ...(options.trustLevel !== undefined ? { trustLevel: options.trustLevel } : {}),\n      ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),\n      ...(options.dryRun !== undefined ? { dryRun: options.dryRun } : {}),\n    };\n    result = await installSkillFromNpm(installOpts);\n  } else {\n    const installOpts: InstallSkillFromGitOptions = {\n      repoUrl: parsed.value,\n      ...(options.ref !== undefined ? { ref: options.ref } : {}),\n      ...(options.trustLevel !== undefined ? { trustLevel: options.trustLevel } : {}),\n      ...(options.dryRun !== undefined ? { dryRun: options.dryRun } : {}),\n    };\n    result = await installSkillFromGit(installOpts);\n  }\n  emitReport(options, result, () => {\n    print(\n      brand(\n        `installed skill '${result.id}' (${result.source.kind}, signatureVerified=${result.signatureVerified})`,\n      ),\n    );\n    if (result.signature !== undefined) {\n      print(`  signature valid: ${result.signature.valid}`);\n    }\n  });\n  return result;\n}\n\n/** @stable */\nexport interface SkillsInspectOptions extends SkillsCommonOptions {\n  readonly name: string;\n}\n\n/** @stable */\nexport async function runSkillsInspect(\n  options: SkillsInspectOptions,\n): Promise<SkillInstallationStatus | null> {\n  const all = auditInstalledSkills();\n  const match = all.find((s) => s.id === options.name) ?? null;\n  emitReport(options, match, () => {\n    const print = options.print ?? defaultPrintSink;\n    if (match === null) {\n      print(brand(`skill '${options.name}' not found in this process registry.`));\n      process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;\n      return;\n    }\n    print(brand(`skill ${match.id}`));\n    print(`  source: ${match.source.kind}`);\n    print(`  trust level: ${match.trustLevel}`);\n    print(`  ignoreScripts: ${match.ignoreScripts}`);\n    print(`  signatureVerified: ${match.signatureVerified}`);\n    print(`  installedAt: ${new Date(match.installedAt).toISOString()}`);\n    if (match.installPath !== undefined) print(`  installPath: ${match.installPath}`);\n    if (match.publisher !== undefined) print(`  publisher: ${match.publisher}`);\n  });\n  return match;\n}\n\n/** @stable */\nexport interface SkillsAuditOptions extends SkillsCommonOptions {}\n\n/** @stable */\nexport function runSkillsAudit(options: SkillsAuditOptions = {}) {\n  const all = auditInstalledSkills();\n  emitReport(options, all, () => {\n    const print = options.print ?? defaultPrintSink;\n    if (all.length === 0) {\n      print(brand('no skills installed in this process registry.'));\n      return;\n    }\n    print(brand(`${all.length} installed skill(s):`));\n    for (const s of all) {\n      const mark = s.signatureVerified ? statusMarker('ok') : statusMarker('warn');\n      print(\n        `  ${mark} ${s.id} (${s.source.kind}, trust=${s.trustLevel}, signatureVerified=${s.signatureVerified})`,\n      );\n    }\n  });\n  return all;\n}\n\n/** @stable */\nexport interface SkillsMigrateFrontmatterOptions extends SkillsCommonOptions {\n  /** Directory to walk. Defaults to `process.cwd()`. */\n  readonly path?: string;\n  readonly recursive?: boolean;\n  readonly apply?: boolean;\n}\n\n/** @stable */\nexport interface SkillsMigrateFrontmatterResult {\n  readonly directory: string;\n  readonly visited: number;\n  readonly migrated: ReadonlyArray<{\n    readonly file: string;\n    readonly result: MigrationResult;\n  }>;\n  readonly applied: boolean;\n}\n\n/** @stable */\nexport async function runSkillsMigrateFrontmatter(\n  options: SkillsMigrateFrontmatterOptions = {},\n): Promise<SkillsMigrateFrontmatterResult> {\n  const root = resolve(options.path ?? process.cwd());\n  const recursive = options.recursive === true;\n  const apply = options.apply === true;\n  const files = await collectSkillMd(root, recursive);\n  const migrated: Array<{ file: string; result: MigrationResult }> = [];\n  for (const file of files) {\n    const raw = await readFile(file, 'utf8');\n    let result: MigrationResult;\n    try {\n      result = migrateFrontmatter(raw, { apply, skillId: file });\n    } catch {\n      continue;\n    }\n    if (result.changed) {\n      if (apply) {\n        await writeFile(file, result.migratedSkillMd, { mode: 0o600 });\n      }\n      migrated.push({ file, result });\n    }\n  }\n  const out: SkillsMigrateFrontmatterResult = Object.freeze({\n    directory: root,\n    visited: files.length,\n    migrated: Object.freeze(migrated),\n    applied: apply,\n  });\n  emitReport(options, out, () => {\n    const print = options.print ?? defaultPrintSink;\n    print(\n      brand(`migrate-frontmatter visited ${out.visited} SKILL.md file(s) under ${out.directory}.`),\n    );\n    if (out.migrated.length === 0) {\n      print(brand('no rewrites required.'));\n      return;\n    }\n    print(\n      brand(\n        `${out.migrated.length} file(s) ${apply ? 'rewritten' : 'would be rewritten (dry-run)'}:`,\n      ),\n    );\n    for (const m of out.migrated) print(`  - ${m.file}`);\n  });\n  return out;\n}\n\nfunction parseSource(input: string): { readonly kind: 'npm' | 'git'; readonly value: string } {\n  if (input.startsWith('npm:')) return { kind: 'npm', value: input.slice(4) };\n  if (input.startsWith('git:')) return { kind: 'git', value: input.slice(4) };\n  if (input.includes('://')) return { kind: 'git', value: input };\n  return { kind: 'npm', value: input };\n}\n\nasync function collectSkillMd(root: string, recursive: boolean): Promise<string[]> {\n  const out: string[] = [];\n  await walk(root, recursive, out);\n  return out;\n}\n\nasync function walk(dir: string, recursive: boolean, acc: string[]): Promise<void> {\n  let entries: string[];\n  try {\n    entries = await readdir(dir);\n  } catch {\n    return;\n  }\n  for (const name of entries) {\n    if (name === 'node_modules' || name === '.git' || name === 'dist') continue;\n    const full = join(dir, name);\n    let s: import('node:fs').Stats;\n    try {\n      s = await stat(full);\n    } catch {\n      continue;\n    }\n    if (s.isDirectory()) {\n      if (recursive) await walk(full, recursive, acc);\n    } else if (name === 'SKILL.md') {\n      acc.push(full);\n    }\n  }\n}\n\n// Touch the loader once so the import is preserved (downstream callers\n// that want to re-load the migrated skill consume `loadSkills(...)`).\nvoid loadSkills;\n"],"mappings":"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"}

package/dist/commands/start.d.ts

@@ -0,0 +1,51 @@
+//#region src/commands/start.d.ts
+/**
+ * `graphorin start [--config <path>]`. Boots the standalone server.
+ *
+ * Exits 1 on every recoverable failure (missing pepper, unresolvable
+ * SecretRef, missing encryption peer, migration error). The CLI never
+ * prints raw secret values; failure messages reference the offending
+ * config path + the suggested `graphorin doctor` follow-up (Phase 15).
+ *
+ * @packageDocumentation
+ */
+/**
+ * Selector for which `SecretsStore` flavour the server activates at
+ * startup. Mirrors `--secrets-source` from DEC-136.
+ *
+ * @stable
+ */
+type SecretsSourceFlag = 'auto' | 'keyring' | 'encrypted-file' | 'env';
+/**
+ * @stable
+ */
+interface StartCommandOptions {
+  readonly config?: string;
+  readonly host?: string;
+  readonly port?: number;
+  readonly logResolved?: boolean;
+  /**
+   * Override the `secrets.source` field of the loaded config. Mirrors
+   * the `--secrets-source <kind>` flag from DEC-136.
+   */
+  readonly secretsSource?: SecretsSourceFlag;
+  /**
+   * Refuse to fall back when the requested primary store is
+   * unavailable. Mirrors `--strict-secrets` from DEC-136.
+   */
+  readonly strictSecrets?: boolean;
+}
+/**
+ * Programmatic entry — used both by the CLI binary and by tests so
+ * the spawn cost of running the binary is paid only when an operator
+ * actually invokes `graphorin start` from a shell.
+ *
+ * @stable
+ */
+declare function runStart(options?: StartCommandOptions): Promise<{
+  readonly host: string;
+  readonly port: number;
+}>;
+//#endregion
+export { SecretsSourceFlag, StartCommandOptions, runStart };
+//# sourceMappingURL=start.d.ts.map

package/dist/commands/start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.d.ts","names":[],"sources":["../../src/commands/start.ts"],"sourcesContent":[],"mappings":";;AAwBA;AAKA;AAwBA;;;;;;;;;;;;;KA7BY,iBAAA;;;;UAKK,mBAAA;;;;;;;;;2BASU;;;;;;;;;;;;;;iBAeL,QAAA,WACX,sBACR"}

package/dist/commands/start.js

@@ -0,0 +1,122 @@
+import { loadConfig } from "../internal/load-config.js";
+import process from "node:process";
+import { RefuseToRunAsRootError, applyProcessHardening } from "@graphorin/security";
+import { ConfigInvalidError, GraphorinServerError, createServer } from "@graphorin/server";
+
+//#region src/commands/start.ts
+/**
+* `graphorin start [--config <path>]`. Boots the standalone server.
+*
+* Exits 1 on every recoverable failure (missing pepper, unresolvable
+* SecretRef, missing encryption peer, migration error). The CLI never
+* prints raw secret values; failure messages reference the offending
+* config path + the suggested `graphorin doctor` follow-up (Phase 15).
+*
+* @packageDocumentation
+*/
+/**
+* Programmatic entry — used both by the CLI binary and by tests so
+* the spawn cost of running the binary is paid only when an operator
+* actually invokes `graphorin start` from a shell.
+*
+* @stable
+*/
+async function runStart(options = {}) {
+	applyHardeningEarly();
+	const loaded = await loadConfig(options.config);
+	if (options.logResolved !== false) process.stderr.write(`[graphorin/cli] resolved config: ${loaded.path}\n`);
+	const overrides = applyCliOverrides(loaded.config, options);
+	let server;
+	try {
+		server = await createServer({ config: overrides });
+	} catch (err) {
+		fatal(err);
+	}
+	if (server === void 0) process.exit(1);
+	const listening = await safeStart(server);
+	process.stderr.write(`[graphorin/cli] @graphorin/server v${server.version} listening on http://${listening.host}:${listening.port}${server.config.server.basePath}\n`);
+	installSignalHandlers(server);
+	return listening;
+}
+/**
+* Merge CLI flag overrides into the loaded `graphorin.config` payload.
+* Exported for unit tests so callers can assert the precedence rules
+* without spinning up a real server.
+*
+* @internal
+*/
+function applyCliOverrides(input, options) {
+	const next = { ...input ?? {} };
+	const serverInput = next.server ?? {};
+	if (options.host !== void 0 || options.port !== void 0) next.server = {
+		...serverInput,
+		...options.host !== void 0 ? { host: options.host } : {},
+		...options.port !== void 0 ? { port: options.port } : {}
+	};
+	const secretsInput = next.secrets ?? {};
+	if (options.secretsSource !== void 0 || options.strictSecrets !== void 0) next.secrets = {
+		...secretsInput,
+		...options.secretsSource !== void 0 ? { source: options.secretsSource } : {},
+		...options.strictSecrets !== void 0 ? { strict: options.strictSecrets } : {}
+	};
+	return next;
+}
+async function safeStart(server) {
+	try {
+		return await server.start();
+	} catch (err) {
+		fatal(err);
+	}
+	process.exit(1);
+}
+function fatal(err) {
+	if (err instanceof ConfigInvalidError) {
+		process.stderr.write("[graphorin/cli] graphorin.config invalid:\n");
+		for (const issue of err.issues) process.stderr.write(`  - ${issue.path.join(".") || "<root>"}: ${issue.message}\n`);
+	} else if (err instanceof GraphorinServerError) {
+		process.stderr.write(`[graphorin/cli] ${err.kind}: ${err.message}\n`);
+		if (err.hint !== void 0) process.stderr.write(`  hint: ${err.hint}\n`);
+	} else if (err instanceof Error) process.stderr.write(`[graphorin/cli] ${err.message}\n`);
+	else process.stderr.write(`[graphorin/cli] unknown error: ${String(err)}\n`);
+	process.exit(1);
+}
+/**
+* Apply the standard hardening hooks before the server bootstraps.
+* Failures (e.g. running as root on Linux/macOS) abort the start with
+* a documented exit code.
+*
+* @internal
+*/
+function applyHardeningEarly() {
+	try {
+		applyProcessHardening({});
+	} catch (err) {
+		if (err instanceof RefuseToRunAsRootError) {
+			process.stderr.write(`[graphorin/cli] ${err.message}\n`);
+			process.stderr.write("[graphorin/cli] hint: drop privileges (systemd User=, k8s runAsNonRoot, docker --user) and retry.\n");
+			process.exit(1);
+		}
+		throw err;
+	}
+}
+function installSignalHandlers(server) {
+	let shuttingDown = false;
+	const onSignal = (signal) => {
+		if (shuttingDown) return;
+		shuttingDown = true;
+		process.stderr.write(`[graphorin/cli] received ${signal}; draining...\n`);
+		server.stop().then(() => {
+			process.stderr.write("[graphorin/cli] graceful shutdown complete\n");
+			process.exit(0);
+		}).catch((err) => {
+			process.stderr.write(`[graphorin/cli] shutdown error: ${err.message}\n`);
+			process.exit(1);
+		});
+	};
+	process.once("SIGTERM", onSignal);
+	process.once("SIGINT", onSignal);
+}
+
+//#endregion
+export { applyHardeningEarly, runStart };
+//# sourceMappingURL=start.js.map