@graphorin/cli 0.6.1 → 0.7.0

package/src/commands/guard.ts

@@ -0,0 +1,144 @@
+/**
+ * `graphorin guard` - inspect the memory-modification guard tier
+ * policy.
+ *
+ * Surface (per Phase 15 § Guard):
+ *
+ *  - `graphorin guard status` - print the four tiers + their guard
+ *    variants (per DEC-153).
+ *  - `graphorin guard explain <toolName>` - derive the tier the
+ *    classifier would assign to a tool with the supplied trust class
+ *    and tags. The CLI accepts the metadata via `--tags` /
+ *    `--trust-level` / `--allowed-secrets` so the explain operation
+ *    matches the runtime classifier without requiring the operator to
+ *    boot the agent.
+ *
+ * @packageDocumentation
+ */
+
+import {
+  type ClassifiableTool,
+  classifyTool,
+  guardVariantForTier,
+  type MemoryGuardTier,
+} from '@graphorin/security';
+
+import {
+  brand,
+  type CommonOutputOptions,
+  defaultPrintSink,
+  emitReport,
+  statusMarker,
+} from '../internal/output.js';
+
+/** @stable */
+export interface GuardCommonOptions extends CommonOutputOptions {}
+
+const TIERS: ReadonlyArray<MemoryGuardTier> = Object.freeze([
+  'pure',
+  'side-effecting-no-memory',
+  'memory-aware',
+  'unknown',
+  'untrusted',
+] as const);
+
+/** @stable */
+export interface GuardStatusEntry {
+  readonly tier: MemoryGuardTier;
+  readonly variant: ReturnType<typeof guardVariantForTier>;
+  readonly description: string;
+}
+
+/** @stable */
+export function runGuardStatus(options: GuardCommonOptions = {}): ReadonlyArray<GuardStatusEntry> {
+  const rows: GuardStatusEntry[] = TIERS.map((tier) =>
+    Object.freeze({
+      tier,
+      variant: guardVariantForTier(tier),
+      description: descriptionFor(tier),
+    }),
+  );
+  emitReport(options, rows, () => {
+    const print = options.print ?? defaultPrintSink;
+    print(brand('memory-modification guard tiers (DEC-153):'));
+    for (const row of rows) {
+      print(`  ${statusMarker('info')} ${row.tier} -> ${row.variant} (${row.description})`);
+    }
+  });
+  return rows;
+}
+
+/** @stable */
+export interface GuardExplainOptions extends GuardCommonOptions {
+  readonly toolName: string;
+  readonly tags?: ReadonlyArray<string>;
+  readonly secretsAllowed?: ReadonlyArray<string>;
+  readonly trustLevel?: 'built-in' | 'user-defined' | 'trusted' | 'untrusted';
+  readonly explicitTier?: MemoryGuardTier;
+}
+
+/** @stable */
+export interface GuardExplainResult {
+  readonly toolName: string;
+  readonly tier: MemoryGuardTier;
+  readonly variant: ReturnType<typeof guardVariantForTier>;
+  readonly reason: string;
+}
+
+/** @stable */
+export function runGuardExplain(options: GuardExplainOptions): GuardExplainResult {
+  const tool: ClassifiableTool = {
+    name: options.toolName,
+    ...(options.tags !== undefined ? { tags: options.tags } : {}),
+    ...(options.secretsAllowed !== undefined ? { secretsAllowed: options.secretsAllowed } : {}),
+    ...(options.trustLevel !== undefined ? { trustLevel: options.trustLevel } : {}),
+    ...(options.explicitTier !== undefined ? { memoryGuardTier: options.explicitTier } : {}),
+  };
+  const tier = classifyTool(tool);
+  const variant = guardVariantForTier(tier);
+  const reason = explainReason(tool, tier);
+  const result: GuardExplainResult = Object.freeze({
+    toolName: options.toolName,
+    tier,
+    variant,
+    reason,
+  });
+  emitReport(options, result, () => {
+    const print = options.print ?? defaultPrintSink;
+    print(
+      brand(
+        `${statusMarker('info')} ${result.toolName} -> tier=${result.tier} (variant=${result.variant})`,
+      ),
+    );
+    print(`  reason: ${result.reason}`);
+  });
+  return result;
+}
+
+function descriptionFor(tier: MemoryGuardTier): string {
+  switch (tier) {
+    case 'pure':
+      return 'no side effects, no guard required';
+    case 'side-effecting-no-memory':
+      return 'side effects but no long-term memory writes';
+    case 'memory-aware':
+      return 'API-boundary guard around memory operations';
+    case 'unknown':
+      return 'audit-only guard (default for unclassified tools)';
+    case 'untrusted':
+      return 'strict full guard with xxhash integrity check';
+  }
+}
+
+function explainReason(tool: ClassifiableTool, tier: MemoryGuardTier): string {
+  if (tool.memoryGuardTier !== undefined) {
+    return `operator-set memoryGuardTier='${tool.memoryGuardTier}' (precedence wins)`;
+  }
+  if (tool.trustLevel === 'untrusted') {
+    return `trustLevel='untrusted' forces tier='untrusted'`;
+  }
+  if (tier === 'memory-aware') {
+    return `tags / secretsAllowed / name match the default memory-tag patterns`;
+  }
+  return `default classification (no memory hints found in tags / secretsAllowed)`;
+}

package/src/commands/index.ts

@@ -0,0 +1,223 @@
+/**
+ * Public command entry points. The CLI binary thin-wraps these
+ * helpers; tests + downstream automations consume them directly so
+ * they never spawn a child process to exercise the contract.
+ *
+ * Phase 14a shipped: `init` / `migrate` / `start`.
+ * Phase 15 added: `doctor`, `token`, `secrets`, `audit`, `storage`,
+ * `memory`, `consolidator`, `triggers`, `auth`, `pricing`, `skills`,
+ * `traces`, `migrate-export`, `migrate-config`, `guard`, `telemetry`,
+ * `tools lint`.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  type AuditCommonOptions,
+  type AuditExportOptions,
+  type AuditExportResult,
+  type AuditPruneOptions,
+  type AuditVerifyResult,
+  runAuditExport,
+  runAuditPrune,
+  runAuditVerify,
+} from './audit.js';
+export {
+  type AuthCommonOptions,
+  type AuthListOptions,
+  type AuthLoginOptions,
+  type AuthRefreshOptions,
+  type AuthRevokeOptions,
+  runAuthList,
+  runAuthLogin,
+  runAuthRefresh,
+  runAuthRevoke,
+  runAuthStatus,
+} from './auth.js';
+export {
+  CONSOLIDATOR_INVALID_TIER_EXIT,
+  type ConsolidatorCommonOptions,
+  type ConsolidatorDlqClearOptions,
+  type ConsolidatorDlqClearResult,
+  type ConsolidatorDlqEntry,
+  type ConsolidatorDlqListOptions,
+  type ConsolidatorSetTierOptions,
+  type ConsolidatorStatusResult,
+  type ConsolidatorStopOptions,
+  runConsolidatorDlqClear,
+  runConsolidatorDlqList,
+  runConsolidatorSetTier,
+  runConsolidatorStatus,
+  runConsolidatorStop,
+} from './consolidator.js';
+export {
+  type DoctorCommandOptions,
+  type DoctorReport,
+  expectedFileModes,
+  runDoctor,
+} from './doctor.js';
+export {
+  type GuardCommonOptions,
+  type GuardExplainOptions,
+  type GuardExplainResult,
+  type GuardStatusEntry,
+  runGuardExplain,
+  runGuardStatus,
+} from './guard.js';
+export { type InitCommandOptions, type InitCommandResult, runInit } from './init.js';
+export {
+  type MemoryActivityConflict,
+  type MemoryActivityEvent,
+  type MemoryActivityOptions,
+  type MemoryActivityResult,
+  type MemoryCitingInsight,
+  type MemoryCommonOptions,
+  type MemoryConflictEntry,
+  type MemoryHistoryEntry,
+  type MemoryInspectEntity,
+  type MemoryInspectFact,
+  type MemoryInspectOptions,
+  type MemoryInspectResult,
+  type MemoryMigrateOptions,
+  type MemoryPruneHistoryOptions,
+  type MemoryPruneHistoryResult,
+  type MemoryReviewItem,
+  type MemoryReviewOptions,
+  type MemoryReviewResult,
+  type MemoryStatusEmbedder,
+  type MemoryStatusResult,
+  type MemoryWhyOptions,
+  type MemoryWhyRecall,
+  type MemoryWhyResult,
+  runMemoryActivity,
+  runMemoryInspect,
+  runMemoryMigrate,
+  runMemoryPruneHistory,
+  runMemoryReview,
+  runMemoryStatus,
+  runMemoryWhy,
+} from './memory.js';
+export { type MigrateCommandOptions, type MigrateCommandResult, runMigrate } from './migrate.js';
+export {
+  type MigrateConfigOptions,
+  type MigrateConfigResult,
+  runMigrateConfig,
+} from './migrate-config.js';
+export {
+  type MigrateExportOptions,
+  type MigrateExportResult,
+  runMigrateExport,
+} from './migrate-export.js';
+export {
+  type PricingCommonOptions,
+  type PricingDiffOptions,
+  type PricingLookupOptions,
+  type PricingMissingOptions,
+  type PricingRefreshOptions,
+  type PricingStatusResult,
+  runPricingDiff,
+  runPricingLookup,
+  runPricingMissing,
+  runPricingRefresh,
+  runPricingStatus,
+} from './pricing.js';
+export {
+  runSecretsDelete,
+  runSecretsGet,
+  runSecretsList,
+  runSecretsRef,
+  runSecretsRotate,
+  runSecretsSet,
+  type SecretsCommonOptions,
+  type SecretsDeleteOptions,
+  type SecretsGetOptions,
+  type SecretsGetResult,
+  type SecretsListOptions,
+  type SecretsRefOptions,
+  type SecretsRefResult,
+  type SecretsRotateOptions,
+  type SecretsSetOptions,
+} from './secrets.js';
+export {
+  runSkillsAudit,
+  runSkillsInspect,
+  runSkillsInstall,
+  runSkillsMigrateFrontmatter,
+  type SkillsAuditOptions,
+  type SkillsCommonOptions,
+  type SkillsInspectOptions,
+  type SkillsInstallOptions,
+  type SkillsMigrateFrontmatterOptions,
+  type SkillsMigrateFrontmatterResult,
+  type SkillTrustLevelInput,
+} from './skills.js';
+export { runStart, type SecretsSourceFlag, type StartCommandOptions } from './start.js';
+export {
+  runStorageBackup,
+  runStorageCleanupBackups,
+  runStorageCompact,
+  runStorageEncrypt,
+  runStorageRekey,
+  runStorageStatus,
+  type StorageBackupOptions,
+  type StorageBackupResult,
+  type StorageCleanupBackupsOptions,
+  type StorageCleanupBackupsResult,
+  type StorageCommonOptions,
+  type StorageCompactOptions,
+  type StorageCompactResult,
+  type StorageEncryptOptions,
+  type StorageRekeyOptions,
+  type StorageStatusResult,
+} from './storage.js';
+export {
+  runTelemetryDisable,
+  runTelemetryEnable,
+  runTelemetryInspect,
+  runTelemetryStatus,
+  type TelemetryStatusResult,
+} from './telemetry.js';
+export {
+  parseDuration,
+  runTokenCreate,
+  runTokenList,
+  runTokenRekey,
+  runTokenRevoke,
+  runTokenRotate,
+  runTokenVerify,
+  type TokenCommonOptions,
+  type TokenCreateOptions,
+  type TokenCreateResult,
+  type TokenListOptions,
+  type TokenRekeyOptions,
+  type TokenRevokeOptions,
+  type TokenRotateOptions,
+  type TokenVerifyOptions,
+  type TokenVerifyResult,
+} from './token.js';
+export {
+  runToolsLint,
+  type ToolsLintOptions,
+  type ToolsLintReport,
+} from './tools-lint.js';
+export {
+  runTracesPrune,
+  runTracesStatus,
+  type TracesCommonOptions,
+  type TracesPruneOptions,
+  type TracesPruneResult,
+  type TracesStatusResult,
+} from './traces.js';
+export {
+  runTriggersDisable,
+  runTriggersFire,
+  runTriggersList,
+  runTriggersPrune,
+  runTriggersStatus,
+  type TriggersCommonOptions,
+  type TriggersDisableOptions,
+  type TriggersFireOptions,
+  type TriggersPruneOptions,
+  type TriggersPruneResult,
+  type TriggersStatusOptions,
+} from './triggers.js';

package/src/commands/init.ts

@@ -0,0 +1,194 @@
+/**
+ * `graphorin init` - interactive bootstrap.
+ *
+ * Writes a fresh `graphorin.config.ts` to the current working
+ * directory (or `--out`), prompts the operator for the cloud-upload
+ * sensitivity tier + storage encryption opt-in, prints the server
+ * pepper hex ONCE, and walks the operator through the working
+ * credential path: persist the pepper (stdin, never argv), migrate,
+ * then mint a real token with `graphorin token create`.
+ *
+ * W-003: init deliberately does NOT emit a token itself. Token
+ * verification requires an HMAC lookup in the auth-token store, which
+ * requires migrations + the pepper - init's contract is "write the
+ * config file, touch nothing else" (pinned by tests), so any token it
+ * printed was guaranteed to 401. Honestly pointing at `token create`
+ * follows the IP-4 precedent (no phantom credentials).
+ *
+ * `--non-interactive` accepts every choice through flags or env vars
+ * so the command works equally well in CI / image-build pipelines.
+ *
+ * @packageDocumentation
+ */
+
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import process from 'node:process';
+
+import { generatePepper } from '@graphorin/security';
+
+import { confirm, select } from '../internal/prompts.js';
+
+/**
+ * @stable
+ */
+export interface InitCommandOptions {
+  readonly out?: string;
+  readonly nonInteractive?: boolean;
+  readonly cloudConsent?: 'public-only' | 'public-and-internal' | 'all-with-warnings';
+  readonly encrypted?: boolean;
+  readonly cwd?: string;
+  /** Test seam: skip writing files (only print the report). */
+  readonly dryRun?: boolean;
+  /** Test seam: redirect stdout/err. */
+  readonly print?: (line: string) => void;
+}
+
+/**
+ * @stable
+ */
+export interface InitCommandResult {
+  readonly configPath: string;
+  readonly serverPepperHex: string;
+  readonly cloudConsent: 'public-only' | 'public-and-internal' | 'all-with-warnings';
+  readonly storageEncrypted: boolean;
+}
+
+/**
+ * @stable
+ */
+export async function runInit(options: InitCommandOptions = {}): Promise<InitCommandResult> {
+  const cwd = options.cwd ?? process.cwd();
+  const target = resolveOutPath(cwd, options.out);
+  const print = options.print ?? ((line: string) => process.stderr.write(`${line}\n`));
+
+  const cloudConsent = await resolveCloudConsent(options);
+  const storageEncrypted = await resolveEncryption(options);
+
+  const pepper = generatePepper();
+  const pepperHex = await pepper.useBuffer((buf) => buf.toString('hex'));
+
+  if (options.dryRun !== true) {
+    if (await fileExists(target)) {
+      throw new Error(
+        `[graphorin/cli] refusing to overwrite existing '${target}'. Move it aside or pass --out <path>.`,
+      );
+    }
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, renderConfig({ cloudConsent, storageEncrypted }), { mode: 0o600 });
+  }
+
+  print(`[graphorin/cli] wrote ${target}`);
+  print(`[graphorin/cli] server pepper hex (store in your keyring as 'graphorin_server_pepper'):`);
+  print(`  ${pepperHex}`);
+  print('');
+  print('Next steps:');
+  // W-041: never put the pepper on argv - shell history and the process
+  // list would hold the key material behind every token HMAC (the
+  // secrets CLI itself refuses plaintext on the command line).
+  print(
+    `  1. Persist the pepper WITHOUT argv: printf '%s' '<hex-from-above>' | graphorin secrets set graphorin_server_pepper --from-stdin`,
+  );
+  print(`  2. Run \`graphorin migrate --config ${target}\` to apply storage migrations.`);
+  print(
+    '  3. Mint your admin token: graphorin token create --label bootstrap --scopes <scopes> (the raw token is shown ONCE).',
+  );
+  print(`  4. Run \`graphorin start --config ${target}\` to launch the server.`);
+
+  return Object.freeze({
+    configPath: target,
+    serverPepperHex: pepperHex,
+    cloudConsent,
+    storageEncrypted,
+  });
+}
+
+function resolveOutPath(cwd: string, out: string | undefined): string {
+  if (out === undefined || out.length === 0) return resolve(cwd, 'graphorin.config.ts');
+  return isAbsolute(out) ? out : resolve(cwd, out);
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveCloudConsent(
+  options: InitCommandOptions,
+): Promise<'public-only' | 'public-and-internal' | 'all-with-warnings'> {
+  if (options.cloudConsent !== undefined) return options.cloudConsent;
+  const envValue = process.env.GRAPHORIN_CLOUD_CONSENT;
+  if (
+    envValue === 'public-only' ||
+    envValue === 'public-and-internal' ||
+    envValue === 'all-with-warnings'
+  ) {
+    return envValue;
+  }
+  if (options.nonInteractive === true) return 'public-and-internal';
+  const choice = await select(
+    'Cloud-upload consent for context sent to providers:',
+    ['public-only', 'public-and-internal', 'all-with-warnings'],
+    'public-and-internal',
+  );
+  return choice as 'public-only' | 'public-and-internal' | 'all-with-warnings';
+}
+
+async function resolveEncryption(options: InitCommandOptions): Promise<boolean> {
+  if (options.encrypted !== undefined) return options.encrypted;
+  if (process.env.GRAPHORIN_STORAGE_ENCRYPTED === '1') return true;
+  if (process.env.GRAPHORIN_STORAGE_ENCRYPTED === '0') return false;
+  if (options.nonInteractive === true) return false;
+  return await confirm('Enable storage encryption (defense-in-depth on top of FDE)?', false);
+}
+
+function renderConfig(input: {
+  readonly cloudConsent: 'public-only' | 'public-and-internal' | 'all-with-warnings';
+  readonly storageEncrypted: boolean;
+}): string {
+  return `import { defineConfig } from '@graphorin/server';
+
+export default defineConfig({
+  server: {
+    host: '127.0.0.1',
+    port: 8080,
+  },
+  auth: {
+    kind: 'token',
+    pepperRef: 'keyring:graphorin_server_pepper',
+  },
+  storage: {
+    path: './.graphorin/data.db',
+    mode: 'server',
+    encryption: ${
+      input.storageEncrypted
+        ? `{
+      enabled: true,
+      passphraseRef: 'keyring:graphorin_db_passphrase',
+    }`
+        : `{ enabled: false }`
+    },
+  },
+  audit: {
+    enabled: ${input.storageEncrypted ? 'true' : 'false'},
+  },
+  secrets: {
+    source: 'auto',
+    strict: false,
+  },
+  observability: {
+    logger: 'json',
+  },
+  // IP-5: no top-level 'defaults' block - the strict server-config
+  // parser rejects unknown keys, so the old render made a fresh
+  // 'graphorin init' fail on the very next migrate/start. The tier you
+  // chose at init is recorded below; enforce it via the memory
+  // package (createMemory contextEngine privacy options):
+  // cloudUploadConsent: ${JSON.stringify(input.cloudConsent)}
+});
+`;
+}