vgxness 1.20.4 → 1.20.6

package/dist/interfaces/cli/cli-flags.js

@@ -0,0 +1,391 @@
+import { resolveMemoryDatabasePath } from '../../memory/storage-paths.js';
+import { permissionCategories } from '../../permissions/policy-evaluator.js';
+import { parseOperationRetryPolicy } from '../../runs/operation-retry.js';
+import { vgxnessSetupDefaults } from '../../setup/setup-defaults.js';
+import { validationFailure } from './cli-help.js';
+function parseArgs(argv) {
+    const positionals = [];
+    const flags = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const current = argv[index];
+        if (current === undefined)
+            continue;
+        if (!current.startsWith('--')) {
+            positionals.push(current);
+            continue;
+        }
+        const [rawKey, inlineValue] = current.slice(2).split('=', 2);
+        if (!rawKey)
+            continue;
+        if (inlineValue !== undefined) {
+            flags[rawKey] = inlineValue;
+            continue;
+        }
+        const next = argv[index + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+            flags[rawKey] = next;
+            index += 1;
+        }
+        else {
+            flags[rawKey] = true;
+        }
+    }
+    return { positionals, flags };
+}
+function databasePathFor(flags, environment) {
+    const resolved = databasePathSelectionFor(flags, environment);
+    return resolved.ok ? { ok: true, value: resolved.value.path } : resolved;
+}
+function databasePathSelectionFor(flags, environment) {
+    const flagPath = flags.db !== undefined ? requiredFlag(flags, 'db') : { ok: true, value: undefined };
+    if (!flagPath.ok)
+        return flagPath;
+    return resolveMemoryDatabasePath({ cwd: environment.cwd, env: environment.env, explicitPath: flagPath.value });
+}
+function requiredFlag(flags, name) {
+    const value = flags[name];
+    return typeof value === 'string' && value.trim() ? { ok: true, value } : validationFailure(`Missing required --${name}`);
+}
+function requiredTrimmedFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    return value.ok ? { ok: true, value: value.value.trim() } : value;
+}
+function optionalStringFlag(flags, name) {
+    const value = flags[name];
+    return typeof value === 'string' && value.trim() ? value : undefined;
+}
+function optionalTrimmedFlag(flags, name) {
+    const value = flags[name];
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    if (typeof value !== 'string' || value.trim().length === 0)
+        return validationFailure(`--${name} must not be empty`);
+    return { ok: true, value: value.trim() };
+}
+function acceptedAtFlag(flags) {
+    const value = optionalTrimmedFlag(flags, 'accepted-at');
+    if (!value.ok)
+        return value;
+    if (value.value === undefined)
+        return { ok: true, value: new Date().toISOString() };
+    const isoDateTimeWithTimezone = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:?\d{2})$/;
+    if (!isoDateTimeWithTimezone.test(value.value))
+        return validationFailure('--accepted-at must be an ISO date-time with explicit timezone');
+    const parsed = new Date(value.value);
+    if (!Number.isFinite(parsed.getTime()))
+        return validationFailure('--accepted-at must be a valid ISO date-time');
+    return { ok: true, value: parsed.toISOString() };
+}
+function codeApprovalPolicyFlag(flags) {
+    const value = optionalStringFlag(flags, 'approval-policy');
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return value === 'ask' || value === 'allow' || value === 'deny' ? { ok: true, value } : validationFailure('--approval-policy must be ask, allow, or deny');
+}
+function codeVerificationModeFlag(flags) {
+    const value = optionalStringFlag(flags, 'verification');
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return value === 'none' || value === 'suggest' || value === 'run' || value === 'repair'
+        ? { ok: true, value }
+        : validationFailure('--verification must be none, suggest, run, or repair');
+}
+function codeTranscriptModeFlag(flags) {
+    const value = optionalStringFlag(flags, 'transcript');
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return value === 'off' || value === 'summary' || value === 'full' ? { ok: true, value } : validationFailure('--transcript must be off, summary, or full');
+}
+function codeMemoryPolicyFlag(flags) {
+    const value = optionalStringFlag(flags, 'memory');
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return value === 'off' || value === 'ask' || value === 'auto' ? { ok: true, value } : validationFailure('--memory must be off, ask, or auto');
+}
+function scopeFlag(flags, name, fallback) {
+    const value = optionalStringFlag(flags, name) ?? fallback;
+    return value === 'project' || value === 'personal' ? { ok: true, value } : validationFailure(`--${name} must be project or personal`);
+}
+function optionalScopeFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return value === 'project' || value === 'personal' ? { ok: true, value } : validationFailure(`--${name} must be project or personal`);
+}
+const providerUserGlobalOnlyMigrationMessage = 'VGX-managed provider configuration is user-global only for OpenCode and Claude. Project/local provider files are treated as external/manual diagnostics and will not be written by VGXNESS. Re-run without the project/local install scope.';
+function opencodeInstallScopeFlag(flags, name) {
+    const value = optionalStringFlag(flags, name) ?? vgxnessSetupDefaults.defaultOpenCodeScope;
+    if (value === 'user' || value === 'global' || value === 'personal')
+        return { ok: true, value: 'user' };
+    if (value === 'project' || value === 'local')
+        return validationFailure(providerUserGlobalOnlyMigrationMessage);
+    return validationFailure(`--${name} must be user, global, or personal`);
+}
+function opencodeDiagnosticScopeFlag(flags, name) {
+    const value = optionalStringFlag(flags, name) ?? vgxnessSetupDefaults.defaultOpenCodeScope;
+    if (value === 'user' || value === 'global' || value === 'personal')
+        return { ok: true, value: 'user' };
+    if (value === 'project')
+        return { ok: true, value };
+    return validationFailure(`--${name} must be user, global, personal, or project`);
+}
+function optionalModeFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return value === 'agent' || value === 'subagent' ? { ok: true, value } : validationFailure(`--${name} must be agent or subagent`);
+}
+function permissionCategoryFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    return permissionCategories.includes(value.value)
+        ? { ok: true, value: value.value }
+        : validationFailure(`--${name} must be one of ${permissionCategories.join(', ')}`);
+}
+function skillSourceFromFlags(flags) {
+    const kind = skillSourceKindFlag(flags, 'source-kind');
+    if (!kind.ok)
+        return kind;
+    if (kind.value === 'path') {
+        const path = requiredFlag(flags, 'source-path');
+        return path.ok ? { ok: true, value: { kind: 'path', path: path.value } } : path;
+    }
+    if (kind.value === 'url') {
+        const url = requiredFlag(flags, 'source-url');
+        return url.ok ? { ok: true, value: { kind: 'url', url: url.value } } : url;
+    }
+    const inlineMetadata = jsonFlag(flags, 'inline-metadata', {});
+    return inlineMetadata.ok ? { ok: true, value: { kind: 'inline', inlineMetadata: inlineMetadata.value } } : inlineMetadata;
+}
+function skillSourceKindFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    return value.value === 'path' || value.value === 'url' || value.value === 'inline'
+        ? { ok: true, value: value.value }
+        : validationFailure(`--${name} must be path, url, or inline`);
+}
+function optionalSkillVersionStatusFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return value === 'draft' || value === 'active' || value === 'deprecated' || value === 'archived'
+        ? { ok: true, value }
+        : validationFailure(`--${name} must be draft, active, deprecated, or archived`);
+}
+function skillTargetTypeFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    return isSkillTargetType(value.value)
+        ? { ok: true, value: value.value }
+        : validationFailure(`--${name} must be agent, subagent, workflow-phase, provider-adapter, or intent-signal`);
+}
+function optionalSkillTargetTypeFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return isSkillTargetType(value)
+        ? { ok: true, value }
+        : validationFailure(`--${name} must be agent, subagent, workflow-phase, provider-adapter, or intent-signal`);
+}
+function skillUsageOutcomeFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    return value.value === 'selected' || value.value === 'injected' || value.value === 'helped' || value.value === 'failed' || value.value === 'neutral'
+        ? { ok: true, value: value.value }
+        : validationFailure(`--${name} must be selected, injected, helped, failed, or neutral`);
+}
+function optionalSkillResolutionUsageFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return value === 'selected' || value === 'injected' ? { ok: true, value } : validationFailure(`--${name} must be selected or injected`);
+}
+function optionalSkillImprovementProposalStatusFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return value === 'draft' || value === 'pending-approval' || value === 'approved' || value === 'rejected' || value === 'cancelled' || value === 'applied'
+        ? { ok: true, value }
+        : validationFailure(`--${name} must be draft, pending-approval, approved, rejected, cancelled, or applied`);
+}
+function skillEvaluationResultStatusFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    return isSkillEvaluationResultStatus(value.value)
+        ? { ok: true, value: value.value }
+        : validationFailure(`--${name} must be passed, failed, needs-review, or not-applicable`);
+}
+function optionalSkillEvaluationResultStatusFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return isSkillEvaluationResultStatus(value) ? { ok: true, value } : validationFailure(`--${name} must be passed, failed, needs-review, or not-applicable`);
+}
+function isSkillEvaluationResultStatus(value) {
+    return value === 'passed' || value === 'failed' || value === 'needs-review' || value === 'not-applicable';
+}
+function isSkillTargetType(value) {
+    return value === 'agent' || value === 'subagent' || value === 'workflow-phase' || value === 'provider-adapter' || value === 'intent-signal';
+}
+function instructionKindFlag(flags) {
+    const value = optionalStringFlag(flags, 'instructions-kind') ?? 'inline';
+    return value === 'inline' || value === 'path' ? { ok: true, value } : validationFailure('--instructions-kind must be inline or path');
+}
+function optionalNumberFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0 ? { ok: true, value: parsed } : validationFailure(`--${name} must be a positive integer`);
+}
+function requiredPositiveIntegerFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    const parsed = Number(value.value);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? { ok: true, value: parsed } : validationFailure(`--${name} must be a positive integer`);
+}
+function taskGrantCategoryFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    return value.value === 'shell' || value.value === 'test-run' || value.value === 'git'
+        ? { ok: true, value: value.value }
+        : validationFailure(`--${name} must be shell, test-run, or git`);
+}
+function optionalTaskGrantStatusFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return value === 'active' || value === 'revoked' || value === 'expired' || value === 'exhausted'
+        ? { ok: true, value }
+        : validationFailure(`--${name} must be active, revoked, expired, or exhausted`);
+}
+function taskGrantExpirationFlag(flags) {
+    const expiresAt = optionalStringFlag(flags, 'expires-at');
+    const ttl = optionalStringFlag(flags, 'ttl');
+    if ((expiresAt === undefined) === (ttl === undefined))
+        return validationFailure('Pass exactly one of --expires-at or --ttl');
+    if (expiresAt !== undefined) {
+        const timestamp = Date.parse(expiresAt);
+        if (!Number.isFinite(timestamp) || new Date(timestamp).toISOString() !== expiresAt)
+            return validationFailure('--expires-at must be a valid ISO date-time');
+        return timestamp > Date.now() ? { ok: true, value: expiresAt } : validationFailure('--expires-at must be in the future');
+    }
+    if (ttl === undefined)
+        return validationFailure('Pass exactly one of --expires-at or --ttl');
+    const match = /^(\d+)(ms|s|m|h|d)$/.exec(ttl);
+    if (match === null)
+        return validationFailure('--ttl must be a positive duration like 30s, 15m, 2h, or 1d');
+    const amount = Number(match[1]);
+    if (!Number.isSafeInteger(amount) || amount <= 0)
+        return validationFailure('--ttl must be a positive duration like 30s, 15m, 2h, or 1d');
+    const unit = match[2];
+    const multiplier = unit === 'ms' ? 1 : unit === 's' ? 1_000 : unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000;
+    return { ok: true, value: new Date(Date.now() + amount * multiplier).toISOString() };
+}
+function optionalRunStatusFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return isRunStatus(value) ? { ok: true, value } : validationFailure(`--${name} must be a valid run status`);
+}
+function finalRunStatusFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    return value.value === 'completed' || value.value === 'failed' || value.value === 'blocked' || value.value === 'cancelled'
+        ? { ok: true, value: value.value }
+        : validationFailure(`--${name} must be completed, failed, blocked, or cancelled`);
+}
+function runOutcomeFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    return value.value === 'success' || value.value === 'partial' || value.value === 'failure' || value.value === 'blocked' || value.value === 'cancelled'
+        ? { ok: true, value: value.value }
+        : validationFailure(`--${name} must be success, partial, failure, blocked, or cancelled`);
+}
+function jsonFlag(flags, name, fallback) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: fallback };
+    try {
+        return { ok: true, value: JSON.parse(value) };
+    }
+    catch (cause) {
+        return { ok: false, error: { code: 'validation_failed', message: `--${name} must be valid JSON`, cause } };
+    }
+}
+function optionalJsonFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    try {
+        return { ok: true, value: JSON.parse(value) };
+    }
+    catch (cause) {
+        return { ok: false, error: { code: 'validation_failed', message: `--${name} must be valid JSON`, cause } };
+    }
+}
+function retryPolicyFlag(flags) {
+    const value = optionalStringFlag(flags, 'policy');
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (cause) {
+        return { ok: false, error: { code: 'validation_failed', message: '--policy must be valid JSON', cause } };
+    }
+    const policy = parseOperationRetryPolicy(parsed);
+    return policy.ok ? { ok: true, value: policy.policy } : validationFailure(`Invalid --policy: ${policy.errors.join('; ')}`);
+}
+function isRunStatus(value) {
+    return (value === 'created' ||
+        value === 'planned' ||
+        value === 'running' ||
+        value === 'needs-human' ||
+        value === 'completed' ||
+        value === 'failed' ||
+        value === 'blocked' ||
+        value === 'cancelled');
+}
+function csvFlag(flags, name) {
+    return (optionalStringFlag(flags, name)
+        ?.split(',')
+        .map((value) => value.trim())
+        .filter(Boolean) ?? []);
+}
+function setupDatabaseFlags(flags) {
+    const dbValue = optionalStringFlag(flags, 'db');
+    const dbPath = optionalStringFlag(flags, 'db-path');
+    if (dbValue === undefined)
+        return { ok: true, value: { mode: vgxnessSetupDefaults.defaultDatabaseMode } };
+    if (dbValue === 'global' || dbValue === 'project-local')
+        return { ok: true, value: { mode: dbValue } };
+    if (dbValue === 'custom')
+        return dbPath === undefined ? validationFailure('--db custom requires --db-path <path>') : { ok: true, value: { mode: 'custom', path: dbPath } };
+    return { ok: true, value: { mode: 'custom', path: dbValue } };
+}
+function setupProviderFlag(flags) {
+    const value = optionalStringFlag(flags, 'provider') ?? vgxnessSetupDefaults.defaultProvider;
+    return value === 'opencode' || value === 'claude' || value === 'none'
+        ? { ok: true, value }
+        : validationFailure('--provider must be opencode, claude, or none');
+}
+function setupInstallModeFlag(flags) {
+    const value = optionalStringFlag(flags, 'mode');
+    if (value !== undefined)
+        return value === 'mcp-only' || value === 'mcp-plus-agents' ? { ok: true, value } : validationFailure('--mode must be mcp-only or mcp-plus-agents');
+    if (flags['mcp-only'] === true || flags['no-agents'] === true)
+        return { ok: true, value: 'mcp-only' };
+    return { ok: true, value: vgxnessSetupDefaults.defaultInstallMode };
+}
+export { acceptedAtFlag, codeApprovalPolicyFlag, codeMemoryPolicyFlag, codeTranscriptModeFlag, codeVerificationModeFlag, csvFlag, databasePathFor, databasePathSelectionFor, finalRunStatusFlag, instructionKindFlag, isRunStatus, isSkillEvaluationResultStatus, isSkillTargetType, jsonFlag, opencodeDiagnosticScopeFlag, opencodeInstallScopeFlag, optionalJsonFlag, optionalModeFlag, optionalNumberFlag, optionalRunStatusFlag, optionalScopeFlag, optionalSkillEvaluationResultStatusFlag, optionalSkillImprovementProposalStatusFlag, optionalSkillResolutionUsageFlag, optionalSkillTargetTypeFlag, optionalSkillVersionStatusFlag, optionalStringFlag, optionalTaskGrantStatusFlag, optionalTrimmedFlag, parseArgs, permissionCategoryFlag, providerUserGlobalOnlyMigrationMessage, requiredFlag, requiredPositiveIntegerFlag, requiredTrimmedFlag, retryPolicyFlag, runOutcomeFlag, scopeFlag, setupDatabaseFlags, setupInstallModeFlag, setupProviderFlag, skillEvaluationResultStatusFlag, skillSourceFromFlags, skillSourceKindFlag, skillTargetTypeFlag, skillUsageOutcomeFlag, taskGrantCategoryFlag, taskGrantExpirationFlag, };

package/dist/interfaces/cli/cli-help.js

@@ -0,0 +1,173 @@
+export function helpText() {
+    return `Usage: vgxness <area> <command> [flags]
+
+Global flags:
+  --help, -h       Show this help.
+  --version, -v    Print the installed package version.
+
+Areas:
+  status [--project <name>] [--change <id>] [--db <path>] [--json]
+  next [--project <name>] [--change <id>] [--db <path>] [--json]
+  resume [--project <name>] [--run-id <id>] [--db <path>] [--json]
+  init [--project <name>] [--provider opencode|claude|none] [--scope user|global|personal] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents] [--json]
+  setup plan [--project <name>] [--provider opencode|claude|none] [--scope user|global|personal] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents] [--json]
+  setup apply --yes [--project <name>] [--provider opencode|claude|none] [--scope user|global|personal] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents]
+  setup reinstall [--yes] [--project <name>] [--scope user|global|personal] [--db global|project-local|custom|<path>] [--db-path <path>] [--mode mcp-only|mcp-plus-agents] [--json]
+  setup backup list --provider opencode [--scope project|user|global] [--target <path>] [--json]
+  setup rollback --backup <path> [--preview|--yes] [--json]
+  setup status [--project <name>] [--scope project|personal] [--db <path>] [--json]
+  doctor [--db <path>] [--project <name>] [--change <id>] [--timeout-ms <ms>] [--json]
+  verification plan --type docs-only|test-only|cli|mcp|sdd-storage|provider-setup|package-release|workflow-runs [--json]
+  verification report save --project <name> --change <id> --file <report.json> [--db <path>] [--json]
+  verification report get --project <name> --change <id> [--db <path>] [--json]
+  Status answers "where am I?" with the human front-door cockpit.
+  Next answers "what should I do now?" with a shorter next-action view.
+  Resume answers "how do I continue interrupted work?" with run inspection guidance.
+  Without --change or --run-id they stay orientation-only and do not open local memory; with --change or --run-id they read SQLite read-only. Pass --json for automation.
+  Setup plan/init default to human-readable read-only output; pass --json for automation. VGX-managed provider configuration is user-global only for OpenCode and Claude; setup apply writes provider config only with --yes and uses the global user DB plus mcp-plus-agents by default. setup reinstall is the explicit safe overwrite path: it replaces only VGXNESS-managed OpenCode entries, preserves unrelated config, and still requires --yes to write.
+  Setup status defaults to human-readable read-only output; pass --json for automation. It never writes provider config or executes providers.
+  Doctor defaults to human-readable output; pass --json for automation.
+  Verification plans are read-only recommendations only; they never execute commands, write provider config, persist results, mutate SDD artifacts, or infer acceptance.
+  Verification reports are manual file-only SDD verify draft artifacts; save/get never execute commands, contact providers, write provider config, or auto-accept verification.
+
+  agents register --project <name> --name <name> --description <text> --instructions <text>
+  agents register --file <agent.json>
+  agents seed load --file <seed.json>
+  agents list [--project <name>] [--scope project|personal]
+  agents get --id <id> | --project <name> --name <name> [--scope project|personal]
+  agents render --provider json|opencode|claude (--id <id> | --project <name> --name <name> [--scope project|personal])
+  agents manager-profile get [--project <name>] [--scope project|personal] [--manager <name>]
+  agents manager-profile set --instructions <text> [--project <name>] [--scope project|personal] [--manager <name>]
+  Seed loading writes only to the local registry; it does not install or write .opencode/, .claude/, or provider config.
+
+  opencode preview --provider opencode (--agent <name> | --agent-id <id>) --project <name> --change <id> --phase <phase> [--scope project|personal]
+  OpenCode CLI preview prints the legacy injection preview JSON for inspection; MCP opencode_handoff_preview is the read-only conversation handoff preview and can be paired with opencode_manager_payload for verbose manager payload details.
+
+  Interactive Home TUI opens from \`vgxness\` in a real terminal; non-TTY use prints safe guidance. Daily SDD progression should happen inside OpenCode through conversation, VGXNESS MCP, and hidden SDD subagents; use status/next/sdd continue for read-only CLI guidance.
+
+  orchestrator preview --project <name> --intent <text> [--change <id>] [--db <path>]
+  Orchestrator preview classifies natural-language requests only; it never executes providers, edits files, records runs, or writes provider config.
+
+  explore|quickfix|plan|build|debug|sdd preview [--project <name>] [--intent <text>]
+  Workflow previews return registry and planner JSON only; they never execute code, edit files, record runs, or write provider config.
+  explore|quickfix|plan|build|debug|sdd run [--project <name>] --intent <text> [--phase <name>] [--agent-id <id>] [--db <path>]
+  Workflow runs record intent plus a safety checkpoint only; they do not call providers, edit files, write provider config, create subagents, or mutate SDD artifacts.
+  explore|quickfix|plan|build|debug|sdd execute --run-id <id> --confirm [--override-escalation] [--workspace <path>] [--executor safe-non-dispatching|provider|command] [--command typecheck|node-version] [--command-cwd <path>] [--command-targets <paths>] [--db <path>]
+  Workflow execute is an explicit safety-gated request; default executor records preflight/ready-to-dispatch state. --executor provider remains guarded and refuses dispatch unless enforceable sandbox/preflight/adapter gates are present. --executor command runs only hardcoded allowlisted argv through bounded-process; no shell strings or provider config targets are allowed.
+
+  approvals list [--run-id <id>] [--db <path>]
+  approvals approve --id <approval-id> [--db <path>]
+  approvals reject --id <approval-id> [--reason <text>] [--db <path>]
+  Approval commands resolve explicit run/preflight approval records; they do not change agent seed permissions or globally allow shell/provider access.
+
+  mcp setup --preview --provider opencode|claude [--db <path>]
+  mcp install opencode --plan [--scope user|global|personal] [--db <path>] [--mcp-only|--no-agents] [--overwrite-vgxness|--reinstall]
+  mcp install opencode --yes [--scope user|global|personal] [--db <path>] [--mcp-only|--no-agents] [--overwrite-vgxness|--reinstall]
+  mcp install claude --plan [--scope user|global|personal] [--db <path>] [--overwrite-vgxness|--reinstall]
+  mcp install claude --yes --run-id <id> [--scope user|global|personal] [--db <path>] [--phase <phase>] [--agent-id <id>] [--overwrite-vgxness|--reinstall]
+  mcp doctor opencode [--scope user|project] [--project-root <path>]
+  mcp doctor [--db <path>] [--project <name>] [--change <id>] [--timeout-ms <ms>]
+  MCP setup preview is read-only; it does not install or write .opencode/, .claude/, or provider config.
+  Without --db, MCP install and setup commands use the vgxness global default database; pass --db .vgx/memory.sqlite for project-local compatibility.
+  OpenCode install defaults to user-global scope and installs mcp.vgxness plus top-level permission.bash=ask, vgxness-manager with bash=deny and native repo tools disabled, and hidden vgxness-sdd-* agents with explicit permissions; use --mcp-only for legacy MCP-only config.
+  Use --overwrite-vgxness (alias --reinstall) to reinstall only VGXNESS-managed OpenCode entries while preserving unrelated config; --yes is still required to write.
+  It writes only after --yes. VGX-managed provider configuration is user-global only for OpenCode and Claude; the OpenCode target is $HOME/.config/opencode/opencode.json.
+  Project/local provider files are external/manual diagnostics and will not be written by VGXNESS. Plans are read-only; applies refuse unsafe existing user-global config and create backups before merge.
+  Claude support is first-class for guarded MCP setup. Claude user/global/personal scopes all target user-global managed config. Confirmed Claude writes narrowly merge mcpServers.vgxness in ~/.claude.json, write ~/.claude/agents/*.md, and manage only the VGXNESS block in ~/.claude/CLAUDE.md. Confirmed Claude writes/CLI execution require VGXNESS run preflight metadata (--run-id, with optional --phase/--agent-id). Status/doctor/change-plan are read-only and do not execute Claude Code.
+
+  skills register --project <name> --name <name> --description <text>
+  skills list [--project <name>] [--scope project|personal]
+  skills get --id <id> | --project <name> --name <name> [--scope project|personal]
+  skills add-version (--id <id> | --project <name> --name <name>) --version <version> --source-kind path|url|inline [--source-path <path>] [--source-url <url>] [--inline-metadata <json>] [--activate]
+  skills attach (--id <id> | --project <name> --name <name>) --target-type agent|subagent|workflow-phase|provider-adapter|intent-signal --target-key <key>
+  skills detach (--id <id> | --project <name> --name <name>) --target-type agent|subagent|workflow-phase|provider-adapter|intent-signal --target-key <key>
+  skills record-usage (--id <id> | --project <name> --name <name>) --outcome selected|injected|helped|failed|neutral [--run-id <id>]
+  skills resolve [--agent <name> | --agent-id <id>] [--project <name>] [--workflow <name>] [--phase <name>] [--intent-signals a,b] [--provider <name>] [--run <id>] [--record-usage selected|injected]
+  skills index --project <name> --scope project|personal
+  skills export --project <name> --scope project|personal
+  skills status --project <name> [--scope project|personal] [--provider opencode] [--mode agent|subagent] [--agent <name-or-id>]
+  skills payload [--agent <name> | --agent-id <id>] [--project <name>] [--workflow <name>] [--phase <name>] [--intent-signals a,b] [--provider <name>]
+  skills propose (--id <id> | --project <name> --name <name>) --proposed-version <version> --source-kind path|url|inline --rationale <text>
+  skills proposals [--skill-id <id>] [--status draft|pending-approval|approved|rejected|cancelled|applied]
+  skills create-scenario (--id <id> --name <scenario> | --project <name> --name <skill> --scenario-name <scenario>) --criteria <json> --created-by <actor> [--proposal <id>] [--version-id <id>]
+  skills list-scenarios (--id <id> | --project <name> --name <name>) [--proposal <id>] [--version-id <id>]
+  skills record-evaluation-result --scenario <id> --status passed|failed|needs-review|not-applicable --result <json> --observed-behavior <text> --evaluator <actor> [--proposal <id>] [--version-id <id>] [--notes <text>]
+  skills list-evaluation-results [--scenario <id>] [--skill-id <id>] [--proposal <id>] [--version-id <id>] [--evaluator <actor>] [--status passed|failed|needs-review|not-applicable]
+  skills get-proposal --proposal <id>
+  skills submit-proposal|approve-proposal|reject-proposal|cancel-proposal|apply-proposal --proposal <id> --actor <name> [--reason <text>]
+  Skills export returns a read-only registry manifest for inspection/automation only; it is not backup, restore, import, or provider/native skill installation.
+
+  subagents register --parent-agent-id <id> --project <name> --name <name> --description <text> --instructions <text>
+  subagents register --file <subagent.json>
+  subagents list --parent-agent-id <id>
+  subagents get --id <id> | --project <name> --name <name> [--scope project|personal]
+
+  No args opens the read-only Home TUI in an interactive terminal; non-TTY prints safe guidance and exits 0 without writing provider config.
+  Setup can run as an interactive TUI or as CLI commands: use setup plan/status for read-only guidance, setup apply --yes for first install, and setup reinstall --yes only after reviewing the VGXNESS-managed overwrite warning.
+  Provider setup support: OpenCode first-class supported default guided install; Claude first-class supported guarded user-global install; project/local provider files are diagnostics only; Antigravity placeholder; Custom/future extension point.
+  Provider config writes/install/apply are external-only and require explicit confirmation.
+
+  sdd status --project <name> --change <id> [--json]
+  sdd next --project <name> --change <id> [--json]
+  sdd continue --project <name> --change <id> [--db <path>] [--json]
+  sdd cockpit --project <name> --change <id> [--json]
+  sdd ready --project <name> --change <id> --phase <phase>
+  sdd save-artifact --project <name> --change <id> --phase <phase> --content <text>
+  sdd accept-artifact --project <name> --change <id> --phase <phase> --actor <human-id> [--display-name <name>] [--note <text>] [--accepted-at <iso>] [--json] [--db <path>]
+  sdd reopen-artifact --project <name> --change <id> --phase <phase> --actor <human-id> [--display-name <name>] [--note <text>] [--json] [--db <path>]
+  sdd get-artifact --project <name> --change <id> --phase <phase> [--json] [--db <path>]
+  sdd list-artifacts --project <name> --change <id> [--json] [--db <path>]
+  SDD artifact reads use the selected local SQLite memory store via --db, VGXNESS_DB_PATH, or the global default.
+  SDD status, next, continue, get-artifact, and list-artifacts default to human-readable output; pass --json for existing automation shapes.
+  SDD continue is a read-only continuation planner; it never executes providers, mutates artifacts, creates runs, writes provider config, or creates openspec/.
+  SDD cockpit defaults to human-readable read-only output; pass --json for metadata-only artifact summaries.
+  SDD accept-artifact records explicit human-only acceptance; save-artifact remains draft-only and never implies acceptance. --accepted-at requires a timezone and is normalized to UTC ISO. Human output is default; pass --json for content-free success output.
+  SDD reopen-artifact records explicit human-only reopening of rejected artifacts only, moving them back to draft so they can be edited and accepted again.
+  sdd export --project <name> --change <id> [--file <package.json>]
+  sdd import --project <name> --change <id> --file <package.json> [--write] [--overwrite]
+
+  memory save --project <name> --type <type> --title <title> --content <text>
+  memory search [--query <text>] [--project <name>] [--type <type>]
+  memory import --file <package.json> --dry-run [--db <path>]
+  memory import --file <package.json> --write (--skip-existing | --overwrite) [--db <path>]
+
+  runs create --project <name> --intent <text> --workflow <name> --phase <name> --agent-id <id> --provider-adapter <name> --model <name>
+  runs list [--project <name>] [--status <status>]
+  runs get --id <id>
+  runs timeline --id <id>
+  runs debug --id <id>
+  runs resume-plan --id <id>
+  runs resume-inspect --id <id>
+  resume-inspect is read-only: it prints checkpoint context, blockers, safety flags, and manual next commands without executing providers, preflight, retry, sandbox, or worktree steps.
+  runs export-snapshot --run-id <id> --project <name> [--file <snapshot.json>]
+  runs checkpoint --run-id <id> --label <text> [--state <json>]
+  runs finish --run-id <id> --status completed|failed|blocked|cancelled --outcome <outcome> [--reason <text>]
+  runs permission-check --run-id <id> --category <category> --operation <name> [--path <path>] [--agent-id <id>] [--destructive] [--external] [--privileged] [--ambiguous]
+  runs preflight --run-id <id> --category <category> --operation <name> [--workspace <path>] [--path <path>] [--provider-tool <name>] [--agent-id <id>] [--destructive] [--external] [--privileged] [--ambiguous]
+  runs preflight output includes workspaceStrategy recommendation JSON and does not create branches, worktrees, or PRs.
+  runs approvals --run <run-id>
+  runs approve|reject|cancel-approval --approval <id> --actor <name> [--reason <text>]
+  runs retry-check --approval <id> [--policy <json>]
+  runs resume-gate --approval <id> [--policy <json>]
+  resume-gate is read-only and plan-only: it prints service planner JSON without preflight, retry admission, executors, provider config writes, sandbox creation, or worktree creation.
+
+  permissions check --category <category> --operation <name> [--path <path>] [--agent-id <id>] [--external] [--privileged]
+
+Storage:
+  Default: global user data vgxness/memory.sqlite (macOS ~/Library/Application Support/vgxness/memory.sqlite; Linux \${XDG_DATA_HOME:-~/.local/share}/vgxness/memory.sqlite; Windows %LOCALAPPDATA%\\vgxness\\memory.sqlite, falling back to %APPDATA%\\vgxness\\memory.sqlite).
+  Precedence: --db <path> (source: flag) > VGXNESS_DB_PATH (source: environment) > global default (source: global-default).
+  Compatibility: pass --db .vgx/memory.sqlite to use the old project-local database explicitly.
+`;
+}
+export function visibleHelpText() {
+    return helpText().replace('  skills register --project <name> --name <name> --description <text>', '  agents resolve [--project <name>] [--scope project|personal] [--workflow <name>] [--phase <name>] [--provider <name>] [--capabilities <csv>] [--task <text>]\n  skills register --project <name> --name <name> --description <text>');
+}
+export function okText(stdout) {
+    return { exitCode: 0, stdout, stderr: '' };
+}
+export function usageFailure(message) {
+    return { exitCode: 1, stdout: '', stderr: `${message}\n\n${visibleHelpText()}` };
+}
+export function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}

package/dist/interfaces/cli/cli-helpers.js

@@ -0,0 +1,77 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { openMemoryDatabase } from '../../memory/sqlite/database.js';
+import { prepareMemoryDatabasePath } from '../../memory/storage-paths.js';
+import { validationFailure } from './cli-help.js';
+function openCliDatabase(path) {
+    const prepared = prepareMemoryDatabasePath(path);
+    if (!prepared.ok)
+        return prepared;
+    return openMemoryDatabase({ path });
+}
+function readJsonFile(path, environment) {
+    try {
+        const parsed = JSON.parse(readFileSync(resolve(environment.cwd, path), 'utf8'));
+        return isRecord(parsed) ? { ok: true, value: parsed } : validationFailure(`Invalid JSON package shape in --file ${path}: expected a JSON object`);
+    }
+    catch (cause) {
+        const message = cause instanceof SyntaxError ? `Invalid JSON in --file ${path}` : `Unable to read --file ${path}`;
+        return { ok: false, error: { code: 'validation_failed', message, cause } };
+    }
+}
+function writeJsonFile(path, value, environment) {
+    try {
+        const outputPath = resolve(environment.cwd, path);
+        mkdirSync(dirname(outputPath), { recursive: true });
+        writeFileSync(outputPath, `${JSON.stringify(value, null, 2)}\n`);
+        return { ok: true, value: undefined };
+    }
+    catch (cause) {
+        return { ok: false, error: { code: 'validation_failed', message: `Unable to write --file ${path}`, cause } };
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function jsonResult(operation) {
+    if (!operation.ok)
+        return resultFailure(operation);
+    return { exitCode: 0, stdout: `${JSON.stringify(operation.value, null, 2)}\n`, stderr: '' };
+}
+function resultFailure(result) {
+    if (result.ok)
+        return { exitCode: 0, stdout: '', stderr: '' };
+    return { exitCode: 1, stdout: '', stderr: `${result.error.code}: ${result.error.message}\n` };
+}
+function toJsonValue(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function formatMemoryImportValidationErrors(errors) {
+    return errors.map((error) => `${error.path}: ${error.message}`).join('; ');
+}
+function validateMemoryImportMode(flags) {
+    if (flags.database !== undefined)
+        return validationFailure('Use --db <path>; --database is not supported');
+    const dryRun = flags['dry-run'] === true;
+    const write = flags.write === true;
+    const skipExisting = flags['skip-existing'] === true;
+    const overwrite = flags.overwrite === true;
+    if (dryRun && write)
+        return validationFailure('Choose exactly one mode: --dry-run or --write');
+    if (!dryRun && !write)
+        return validationFailure('Missing import mode: pass --dry-run or --write');
+    if (skipExisting && overwrite)
+        return validationFailure('Choose exactly one duplicate policy: --skip-existing or --overwrite');
+    if (dryRun && (skipExisting || overwrite))
+        return validationFailure('--skip-existing and --overwrite are write-mode duplicate policies and cannot be used with --dry-run');
+    if (write) {
+        if (skipExisting === overwrite)
+            return validationFailure('--write requires exactly one duplicate policy: --skip-existing or --overwrite');
+        return { ok: true, value: skipExisting ? 'skip-existing' : 'overwrite' };
+    }
+    return { ok: true, value: 'dry-run' };
+}
+export { formatMemoryImportValidationErrors, isJsonObject, isRecord, jsonResult, openCliDatabase, readJsonFile, resultFailure, toJsonValue, validateMemoryImportMode, writeJsonFile, };

package/dist/interfaces/cli/cli-types.js

@@ -0,0 +1 @@
+export {};