@graphorin/cli 0.6.0 → 0.7.0

package/src/commands/secrets.ts

@@ -0,0 +1,309 @@
+/**
+ * `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
+ */
+
+import { stdin } from 'node:process';
+
+import type { SecretMetadata } from '@graphorin/core/contracts';
+import {
+  createSecretsStore,
+  getActiveSecretsStore,
+  parseSecretRef,
+  resolveSecret,
+  type SecretsStoreKind,
+  SecretValue,
+} from '@graphorin/security';
+
+import { EXIT_CODES } from '../internal/exit.js';
+import {
+  brand,
+  type CommonOutputOptions,
+  defaultPrintSink,
+  emitReport,
+  statusMarker,
+} from '../internal/output.js';
+
+/** @stable */
+export interface SecretsCommonOptions extends CommonOutputOptions {
+  /** Mirrors `--secrets-source` per DEC-136. */
+  readonly secretsSource?: SecretsStoreKind;
+  /** Mirrors `--strict-secrets` per DEC-136. */
+  readonly strictSecrets?: boolean;
+}
+
+/** @stable */
+export interface SecretsListOptions extends SecretsCommonOptions {}
+
+/** @stable */
+export async function runSecretsList(
+  options: SecretsListOptions = {},
+): Promise<ReadonlyArray<SecretMetadata>> {
+  const store = await openStore(options);
+  const list = await store.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 */
+export interface SecretsGetOptions extends SecretsCommonOptions {
+  readonly key: string;
+  /**
+   * When `true`, print the raw value through the human report. The
+   * default is to print only structured metadata so the bytes do not
+   * surface in shell history.
+   */
+  readonly reveal?: boolean;
+}
+
+/** @stable */
+export interface SecretsGetResult {
+  readonly key: string;
+  readonly found: boolean;
+  /** Only present when `reveal: true` AND the secret exists. */
+  readonly value?: string;
+}
+
+/** @stable */
+export async function runSecretsGet(options: SecretsGetOptions): Promise<SecretsGetResult> {
+  const store = await openStore(options);
+  const value = await store.get(options.key);
+  if (value === null) {
+    const out: SecretsGetResult = Object.freeze({ key: options.key, found: false });
+    emitReport(options, out, () => {
+      const print = options.print ?? defaultPrintSink;
+      print(brand(`secret '${options.key}' not found.`));
+    });
+    // W-002: exit code independent of --json (see runAuditVerify).
+    process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;
+    return out;
+  }
+  if (options.reveal === true) {
+    const raw = await value.use((s) => String(s));
+    const out: SecretsGetResult = Object.freeze({ key: options.key, found: true, value: raw });
+    emitReport(options, out, () => {
+      const print = options.print ?? defaultPrintSink;
+      print(brand(`secret '${options.key}' resolved (length=${raw.length})`));
+      print(`  ${raw}`);
+    });
+    return out;
+  }
+  const out: SecretsGetResult = Object.freeze({ key: options.key, found: true });
+  emitReport(options, out, () => {
+    const print = options.print ?? defaultPrintSink;
+    print(brand(`secret '${options.key}' found (use --reveal to print the bytes)`));
+  });
+  return out;
+}
+
+/** @stable */
+export interface SecretsSetOptions extends SecretsCommonOptions {
+  readonly key: string;
+  readonly value?: string;
+  /** When `true`, read the value from stdin. */
+  readonly fromStdin?: boolean;
+}
+
+/** @stable */
+export async function runSecretsSet(options: SecretsSetOptions): Promise<{ readonly ok: true }> {
+  const store = await openStore(options);
+  let raw = options.value;
+  if (raw === undefined && options.fromStdin === true) {
+    raw = await readStdin();
+  }
+  if (raw === undefined) {
+    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 } as const, () => {
+    const print = options.print ?? defaultPrintSink;
+    print(brand(`secret '${options.key}' written.`));
+  });
+  return { ok: true };
+}
+
+/** @stable */
+export interface SecretsDeleteOptions extends SecretsCommonOptions {
+  readonly key: string;
+}
+
+/** @stable */
+export async function runSecretsDelete(
+  options: SecretsDeleteOptions,
+): Promise<{ readonly ok: true }> {
+  const store = await openStore(options);
+  await store.delete(options.key);
+  emitReport(options, { ok: true } as const, () => {
+    const print = options.print ?? defaultPrintSink;
+    print(brand(`secret '${options.key}' deleted.`));
+  });
+  return { ok: true };
+}
+
+/** @stable */
+export interface SecretsRefOptions extends CommonOutputOptions {
+  readonly uri: string;
+  readonly reveal?: boolean;
+}
+
+/** @stable */
+export interface SecretsRefResult {
+  readonly uri: string;
+  readonly scheme: string;
+  readonly resolved: boolean;
+  readonly length?: number;
+  readonly value?: string;
+}
+
+/**
+ * Test resolution of a `SecretRef` URI. The CLI parses the URI first
+ * (sanity check + scheme echo), then resolves through the registered
+ * resolver chain.
+ *
+ * @stable
+ */
+export async function runSecretsRef(options: SecretsRefOptions): Promise<SecretsRefResult> {
+  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)) : undefined;
+    const out: SecretsRefResult = Object.freeze({
+      uri: options.uri,
+      scheme: parsed.scheme,
+      resolved: true,
+      length,
+      ...(raw !== undefined ? { value: raw } : {}),
+    });
+    emitReport(options, out, () => {
+      const print = options.print ?? defaultPrintSink;
+      print(
+        brand(
+          `${statusMarker('ok')} resolved '${parsed.scheme}' ref (length=${length}${raw !== undefined ? `, value='${raw}'` : ''})`,
+        ),
+      );
+    });
+    return out;
+  } catch (err) {
+    const out: SecretsRefResult = Object.freeze({
+      uri: options.uri,
+      scheme: parsed.scheme,
+      resolved: false,
+    });
+    emitReport(options, out, () => {
+      const print = options.print ?? defaultPrintSink;
+      print(
+        brand(`${statusMarker('fail')} ${parsed.scheme} ref failed: ${(err as Error).message}`),
+      );
+    });
+    // W-002: exit code independent of --json (see runAuditVerify).
+    process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;
+    return out;
+  }
+}
+
+/** @stable */
+export interface SecretsRotateOptions extends SecretsCommonOptions {
+  readonly key: string;
+  readonly newValue?: string;
+  readonly fromStdin?: boolean;
+}
+
+/**
+ * `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
+ */
+export async function runSecretsRotate(
+  options: SecretsRotateOptions,
+): Promise<{ readonly ok: true }> {
+  const store = await openStore(options);
+  const existing = await store.get(options.key);
+  if (existing === 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 === undefined && options.fromStdin === true) raw = await readStdin();
+  if (raw === undefined) {
+    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 } as const, () => {
+    const print = options.print ?? defaultPrintSink;
+    print(brand(`secret '${options.key}' rotated.`));
+  });
+  return { ok: true };
+}
+
+async function openStore(options: SecretsCommonOptions) {
+  // Reuse the per-process active store when the caller did not request
+  // a different kind. The singleton matches the running server / lib
+  // process so consecutive CLI invocations within the same process
+  // address the same backing store (this matters for the in-memory
+  // store + for subprocess CLI flows that share a parent's resolver
+  // chain via env vars).
+  if (options.secretsSource === undefined) {
+    const active = getActiveSecretsStore();
+    if (active !== undefined) return active;
+  }
+  return await createSecretsStore({
+    ...(options.secretsSource !== undefined ? { kind: options.secretsSource } : {}),
+    ...(options.strictSecrets !== undefined ? { strict: options.strictSecrets } : {}),
+  });
+}
+
+async function readStdin(): Promise<string> {
+  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);
+  });
+}

package/src/commands/skills.ts

@@ -0,0 +1,272 @@
+/**
+ * `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
+ */
+
+import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import process from 'node:process';
+
+import {
+  auditInstalledSkills,
+  type InstallSkillFromGitOptions,
+  type InstallSkillFromNpmOptions,
+  installSkillFromGit,
+  installSkillFromNpm,
+  type SkillInstallationStatus,
+} from '@graphorin/security';
+import { loadSkills, type MigrationResult, migrateFrontmatter } from '@graphorin/skills';
+
+import { EXIT_CODES } from '../internal/exit.js';
+import { checkOfflineModeBlocked } from '../internal/offline.js';
+import {
+  brand,
+  type CommonOutputOptions,
+  defaultPrintSink,
+  emitReport,
+  statusMarker,
+} from '../internal/output.js';
+
+/** @stable */
+export interface SkillsCommonOptions extends CommonOutputOptions {}
+
+/** @stable */
+export type SkillTrustLevelInput = 'trusted' | 'trusted-with-scripts' | 'untrusted';
+
+/** @stable */
+export 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 */
+export async function runSkillsInstall(
+  options: SkillsInstallOptions,
+): Promise<SkillInstallationStatus> {
+  if (
+    !checkOfflineModeBlocked('skills install', {
+      ...(options.print !== undefined ? { print: options.print } : {}),
+    })
+  ) {
+    process.exit(EXIT_CODES.RECOVERABLE_FAILURE);
+  }
+  const print = options.print ?? defaultPrintSink;
+  const parsed = parseSource(options.source);
+  let result: SkillInstallationStatus;
+  if (parsed.kind === 'npm') {
+    const installOpts: InstallSkillFromNpmOptions = {
+      packageName: parsed.value,
+      ...(options.version !== undefined ? { version: options.version } : {}),
+      ...(options.trustLevel !== undefined ? { trustLevel: options.trustLevel } : {}),
+      ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+      ...(options.dryRun !== undefined ? { dryRun: options.dryRun } : {}),
+    };
+    result = await installSkillFromNpm(installOpts);
+  } else {
+    const installOpts: InstallSkillFromGitOptions = {
+      repoUrl: parsed.value,
+      ...(options.ref !== undefined ? { ref: options.ref } : {}),
+      ...(options.trustLevel !== undefined ? { trustLevel: options.trustLevel } : {}),
+      ...(options.dryRun !== undefined ? { dryRun: options.dryRun } : {}),
+    };
+    result = await installSkillFromGit(installOpts);
+  }
+  emitReport(options, result, () => {
+    print(
+      brand(
+        `installed skill '${result.id}' (${result.source.kind}, signatureVerified=${result.signatureVerified})`,
+      ),
+    );
+    if (result.signature !== undefined) {
+      print(`  signature valid: ${result.signature.valid}`);
+    }
+  });
+  return result;
+}
+
+/** @stable */
+export interface SkillsInspectOptions extends SkillsCommonOptions {
+  readonly name: string;
+}
+
+/** @stable */
+export async function runSkillsInspect(
+  options: SkillsInspectOptions,
+): Promise<SkillInstallationStatus | null> {
+  const all = auditInstalledSkills();
+  const match = all.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.`));
+      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 !== undefined) print(`  installPath: ${match.installPath}`);
+    if (match.publisher !== undefined) print(`  publisher: ${match.publisher}`);
+  });
+  // W-002: exit code independent of --json (see runAuditVerify).
+  if (match === null) process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;
+  return match;
+}
+
+/** @stable */
+export interface SkillsAuditOptions extends SkillsCommonOptions {}
+
+/** @stable */
+export function runSkillsAudit(options: SkillsAuditOptions = {}) {
+  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) {
+      const mark = s.signatureVerified ? statusMarker('ok') : statusMarker('warn');
+      print(
+        `  ${mark} ${s.id} (${s.source.kind}, trust=${s.trustLevel}, signatureVerified=${s.signatureVerified})`,
+      );
+    }
+  });
+  return all;
+}
+
+/** @stable */
+export interface SkillsMigrateFrontmatterOptions extends SkillsCommonOptions {
+  /** Directory to walk. Defaults to `process.cwd()`. */
+  readonly path?: string;
+  readonly recursive?: boolean;
+  readonly apply?: boolean;
+}
+
+/** @stable */
+export interface SkillsMigrateFrontmatterResult {
+  readonly directory: string;
+  readonly visited: number;
+  readonly migrated: ReadonlyArray<{
+    readonly file: string;
+    readonly result: MigrationResult;
+  }>;
+  readonly applied: boolean;
+}
+
+/** @stable */
+export async function runSkillsMigrateFrontmatter(
+  options: SkillsMigrateFrontmatterOptions = {},
+): Promise<SkillsMigrateFrontmatterResult> {
+  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: Array<{ file: string; result: MigrationResult }> = [];
+  for (const file of files) {
+    const raw = await readFile(file, 'utf8');
+    let result: MigrationResult;
+    try {
+      result = migrateFrontmatter(raw, { apply, skillId: file });
+    } catch {
+      continue;
+    }
+    if (result.changed) {
+      if (apply) {
+        await writeFile(file, result.migratedSkillMd, { mode: 0o600 });
+      }
+      migrated.push({ file, result });
+    }
+  }
+  const out: SkillsMigrateFrontmatterResult = 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: string): { readonly kind: 'npm' | 'git'; readonly value: string } {
+  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: string, recursive: boolean): Promise<string[]> {
+  const out: string[] = [];
+  await walk(root, recursive, out);
+  return out;
+}
+
+async function walk(dir: string, recursive: boolean, acc: string[]): Promise<void> {
+  let entries: string[];
+  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: import('node:fs').Stats;
+    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);
+    }
+  }
+}
+
+// Touch the loader once so the import is preserved (downstream callers
+// that want to re-load the migrated skill consume `loadSkills(...)`).
+void loadSkills;