@ductape/cli 0.2.23 → 0.3.1

package/dist/index.js

@@ -18,7 +18,7 @@ import { runDb, runDbContext } from './commands/db.js';
 import { runDbMigrate, runDbMigrateStatus, runDbMigrateRollback } from './commands/db-migrate.js';
 import { runDbSchemaGenerate, runDbSchemaPush } from './commands/db-schema.js';
 import { runGraph } from './commands/graph.js';
-import { runSecrets } from './commands/secrets.js';
+import { runSecretImportEnv, runSecrets } from './commands/secrets.js';
 import { runWorkspacesCurrent, runWorkspacesList, runWorkspacesRefresh, runWorkspacesUse, } from './commands/workspaces.js';
 import { runGeneratePayload, runGenerateSnippet } from './commands/generate.js';
 import { runCompletion } from './commands/completion.js';
@@ -26,13 +26,31 @@ import { runProducts, runProductApps, runProductComponents, runProductEnvironmen
 import { runApps } from './commands/apps.js';
 import { runAppsImport } from './commands/apps-import.js';
 import { runApply } from './commands/apply.js';
+import { runMigrateCodebase } from './commands/migrate-codebase.js';
+import { runMigrationReviewInit, runMigrationReviewRecord, runMigrationReviewFollowUp, runMigrationReviewExclude, runMigrationReviewParity, runMigrationReviewReopen, runMigrationReviewMove, runMigrationReviewMerge, runMigrationReviewSign, runMigrationReviewSnapshot, runMigrationReviewVerifySignature, runMigrationReviewValidate, } from './commands/migration-review.js';
+import { runMigrationSliceDefine, runMigrationSliceInit, runMigrationSliceValidate, } from './commands/migration-slice.js';
+import { runMigrationPortfolioInit, runMigrationPortfolioPropose, runMigrationPortfolioValidate, } from './commands/migration-portfolio.js';
+import { runMigrationDatabaseInit, runMigrationDatabaseValidate } from './commands/migration-database.js';
+import { runMigrationEnvironmentsReconcile } from './commands/migration-environments.js';
+import { runMigrationProductsInit, runMigrationProductsValidate } from './commands/migration-products.js';
+import { runMigrationSecretsInit, runMigrationSecretsValidate } from './commands/migration-secrets.js';
+import { runMigrationE2EFinal, runMigrationE2EInit, runMigrationE2EValidate, } from './commands/migration-e2e.js';
+import { runMigrationGeneratedInit, runMigrationGeneratedValidate, } from './commands/migration-generated.js';
+import { runMigrationAssuranceValidate } from './commands/migration-assurance.js';
+import { runMigrationVerificationValidate } from './commands/migration-verification.js';
+import { runMigrationArtifactMigrate, runMigrationArtifactRecover, runMigrationArtifactSchemas, runMigrationArtifactValidate, } from './commands/migration-artifact.js';
+import { runMigrationCapabilities } from './commands/migration-capabilities.js';
+import { structuredMigrationError } from './lib/migration-artifact.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '../package.json'), 'utf8'));
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function wrap(fn) {
     return (...args) => {
-        Promise.resolve(fn(...args)).catch((err) => {
-            console.error(err instanceof Error ? err.message : err);
+        Promise.resolve().then(() => fn(...args)).catch((err) => {
+            const command = process.argv[2] ?? '';
+            console.error(command === 'migrate-codebase' || command.startsWith('migration-')
+                ? structuredMigrationError(err)
+                : err instanceof Error ? err.message : err);
             process.exit(1);
         });
     };
@@ -143,6 +161,331 @@ program
     env: opts.env,
     language: opts.language,
 })));
+program
+    .command('migrate-codebase')
+    .description('Inspect a codebase and write advisory guidance for an AI-led Ductape migration')
+    .option('-C, --source <path>', 'Existing codebase', process.cwd())
+    .requiredOption('--e2e-baseline <path>', 'Passing immutable original E2E baseline manifest')
+    .option('--mode <mode>', 'in-place | new-codebase', 'new-codebase')
+    .option('--destination <path>', 'Destination for new-codebase mode')
+    .option('--product <tag>', 'Ductape product tag')
+    .option('--name <name>', 'Product display name')
+    .option('--database <tag>', 'Database tag for generated Ductape schema')
+    .option('--max-file-bytes <bytes>', 'Maximum reviewable file size', '2000000')
+    .option('--include <patterns>', 'Comma-separated repository-relative glob patterns')
+    .option('--exclude <patterns>', 'Comma-separated repository-relative glob patterns')
+    .option('--ensure-product', 'Create the product when it does not exist')
+    .option('--write', 'Write redacted advisory artifacts only; never writes application code or executable assets')
+    .option('--mcp-client-name <name>', 'Protocol-asserted MCP client name (unverified)', undefined)
+    .option('--mcp-client-version <version>', 'Protocol-asserted MCP client version (unverified)', undefined)
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrateCodebase({
+    source: opts.source,
+    e2eBaseline: opts.e2eBaseline,
+    mode: opts.mode,
+    destination: opts.destination,
+    product: opts.product,
+    name: opts.name,
+    database: opts.database,
+    maxFileBytes: Number(opts.maxFileBytes),
+    include: opts.include ? String(opts.include).split(',').map((value) => value.trim()).filter(Boolean) : [],
+    exclude: opts.exclude ? String(opts.exclude).split(',').map((value) => value.trim()).filter(Boolean) : [],
+    ensureProduct: Boolean(opts.ensureProduct),
+    write: Boolean(opts.write),
+    json: Boolean(opts.json),
+    mcpClientName: opts.mcpClientName,
+    mcpClientVersion: opts.mcpClientVersion,
+})));
+const migrationE2E = program
+    .command('migration-e2e')
+    .description('Bind the original E2E suite and validate final migration parity without executing tests');
+migrationE2E
+    .command('init')
+    .requiredOption('-C, --source <path>', 'Original codebase')
+    .requiredOption('--definition <path>', 'JSON containing suite files, command, and passing baseline evidence')
+    .option('--output <path>', 'Baseline manifest output path')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationE2EInit({ ...opts, json: Boolean(opts.json) })));
+migrationE2E
+    .command('final')
+    .requiredOption('--manifest <path>', 'Original E2E baseline manifest')
+    .requiredOption('--evidence <path>', 'JSON containing passing final-run evidence')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationE2EFinal({ ...opts, json: Boolean(opts.json) })));
+migrationE2E
+    .command('validate')
+    .requiredOption('--manifest <path>', 'Original E2E baseline manifest')
+    .option('--strict', 'Fail unless baseline integrity and the final run are verified')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationE2EValidate({ ...opts, strict: Boolean(opts.strict), json: Boolean(opts.json) })));
+const migrationGenerated = program
+    .command('migration-generated')
+    .description('Validate generated contracts and locally modified vendor source without executing generators');
+migrationGenerated
+    .command('init')
+    .requiredOption('--analysis <path>', 'Migration analysis containing generated-source hints')
+    .requiredOption('--definition <path>', 'Contextually reviewed generated/vendor definition JSON')
+    .option('--output <path>', 'Evidence manifest output path')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationGeneratedInit({ ...opts, json: Boolean(opts.json) })));
+migrationGenerated
+    .command('validate')
+    .requiredOption('--file <path>', 'Generated/vendor evidence manifest')
+    .option('--strict', 'Fail on stale inputs, regeneration mismatch, or missing contract evidence')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationGeneratedValidate({
+    ...opts,
+    strict: Boolean(opts.strict),
+    json: Boolean(opts.json),
+})));
+program
+    .command('migration-assurance')
+    .description('Validate repository-wide component, session, resilience, runtime, API, and SDK evidence')
+    .requiredOption('--file <path>', 'Versioned migration assurance JSON')
+    .option('--strict', 'Fail unless every required assurance category is evidenced and tested')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationAssuranceValidate({
+    file: opts.file,
+    strict: Boolean(opts.strict),
+    json: Boolean(opts.json),
+})));
+program
+    .command('migration-capabilities')
+    .description('Print the source-verified capability matrix for supported SDK language/version pairs')
+    .option('--language <language>', 'typescript | go | java | dotnet')
+    .option('--version <version>', 'Exact supported SDK version')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationCapabilities({
+    language: opts.language,
+    version: opts.version,
+    json: Boolean(opts.json),
+})));
+program
+    .command('migration-verification')
+    .description('Validate cited automation evidence for large-repo, parity, frontend, database, and asset migration')
+    .requiredOption('--file <path>', 'Versioned migration verification matrix JSON')
+    .option('--strict', 'Fail unless every verification requirement is passing, cited, and current')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationVerificationValidate({
+    file: opts.file,
+    strict: Boolean(opts.strict),
+    json: Boolean(opts.json),
+})));
+const migrationArtifact = program
+    .command('migration-artifact')
+    .description('Validate, recover, and version-migrate secured migration JSON artifacts');
+migrationArtifact.command('validate').requiredOption('--file <path>').option('--json')
+    .action(wrap((opts) => runMigrationArtifactValidate({ file: opts.file, json: Boolean(opts.json) })));
+migrationArtifact.command('recover').requiredOption('--file <path>').option('--json')
+    .action(wrap((opts) => runMigrationArtifactRecover({ file: opts.file, json: Boolean(opts.json) })));
+migrationArtifact.command('migrate').requiredOption('--file <path>').requiredOption('--output <path>').option('--json')
+    .action(wrap((opts) => runMigrationArtifactMigrate({ file: opts.file, output: opts.output, json: Boolean(opts.json) })));
+migrationArtifact.command('schemas').option('--json')
+    .action(wrap((opts) => runMigrationArtifactSchemas(Boolean(opts.json))));
+const migrationReview = program
+    .command('migration-review')
+    .description('Track and validate an AI-led migration review without generating application code');
+migrationReview
+    .command('init')
+    .requiredOption('--analysis <path>', 'Path to migration-guidance/analysis.json')
+    .option('--output <path>', 'Review ledger output path')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationReviewInit({
+    analysis: opts.analysis,
+    output: opts.output,
+    json: Boolean(opts.json),
+})));
+migrationReview
+    .command('record')
+    .requiredOption('--ledger <path>', 'Review ledger path')
+    .requiredOption('--file <path>', 'Repository-relative file')
+    .requiredOption('--data <path>', 'JSON file containing contextual review evidence')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationReviewRecord({ ...opts, json: Boolean(opts.json) })));
+migrationReview
+    .command('follow-up')
+    .requiredOption('--ledger <path>', 'Review ledger path')
+    .requiredOption('--file <path>', 'Repository-relative source file')
+    .requiredOption('--follow-up <path>', 'Repository-relative file discovered during review')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationReviewFollowUp({ ...opts, json: Boolean(opts.json) })));
+migrationReview
+    .command('exclude')
+    .requiredOption('--ledger <path>', 'Review ledger path')
+    .requiredOption('--file <path>', 'Repository-relative file')
+    .requiredOption('--classification <type>', 'generated | vendor | build | snapshot | other')
+    .requiredOption('--reason <text>', 'Why the file is excluded')
+    .option('--owner <text>', 'Owner or source of the excluded file')
+    .option('--generator <text>', 'Generator command/tool (required for generated)')
+    .option('--regeneration-test <text>', 'Regeneration verification (required for generated)')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationReviewExclude({ ...opts, json: Boolean(opts.json) })));
+migrationReview
+    .command('parity')
+    .requiredOption('--ledger <path>', 'Review ledger path')
+    .requiredOption('--file <path>', 'Repository-relative file')
+    .requiredOption('--concern <type>', 'interface | functional | operational')
+    .requiredOption('--status <status>', 'verified | not_applicable')
+    .option('--evidence <text>', 'Concrete parity evidence (required for verified)')
+    .option('--reason <text>', 'Reason (required for not_applicable)')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationReviewParity({ ...opts, json: Boolean(opts.json) })));
+migrationReview
+    .command('reopen')
+    .requiredOption('--ledger <path>', 'Review ledger path')
+    .requiredOption('--file <path>', 'Repository-relative file')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationReviewReopen({ ...opts, json: Boolean(opts.json) })));
+migrationReview
+    .command('move')
+    .requiredOption('--ledger <path>', 'Review ledger path')
+    .requiredOption('--from <path>', 'Previous repository-relative file')
+    .requiredOption('--to <path>', 'New repository-relative file with identical reviewed content')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationReviewMove({ ...opts, json: Boolean(opts.json) })));
+migrationReview
+    .command('merge')
+    .requiredOption('--base <path>', 'Common-base review ledger')
+    .requiredOption('--current <path>', 'Current review ledger')
+    .requiredOption('--incoming <path>', 'Incoming parallel review ledger')
+    .requiredOption('--output <path>', 'New merged ledger; existing ledgers are never overwritten')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationReviewMerge({ ...opts, json: Boolean(opts.json) })));
+migrationReview
+    .command('sign')
+    .requiredOption('--ledger <path>', 'Review ledger')
+    .requiredOption('--private-key <path>', 'Trusted Ed25519 private key PEM file')
+    .requiredOption('--key-id <id>', 'Trusted signing identity')
+    .option('--output <path>', 'Detached signature output')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationReviewSign({ ...opts, json: Boolean(opts.json) })));
+migrationReview
+    .command('verify-signature')
+    .requiredOption('--ledger <path>', 'Review ledger')
+    .requiredOption('--signature <path>', 'Detached signature JSON')
+    .requiredOption('--public-key <path>', 'Trusted Ed25519 public key PEM file')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationReviewVerifySignature({ ...opts, json: Boolean(opts.json) })));
+migrationReview
+    .command('snapshot')
+    .requiredOption('--ledger <path>', 'Review ledger path')
+    .requiredOption('--file <path>', 'Repository-relative reviewed file')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationReviewSnapshot({
+    ledger: opts.ledger,
+    file: opts.file,
+    json: Boolean(opts.json),
+})));
+migrationReview
+    .command('validate')
+    .requiredOption('--ledger <path>', 'Review ledger path')
+    .option('--strict', 'Fail unless coverage, staleness, context, follow-ups, and parity are complete')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationReviewValidate({
+    ledger: opts.ledger,
+    strict: Boolean(opts.strict),
+    json: Boolean(opts.json),
+})));
+const migrationSlice = program
+    .command('migration-slice')
+    .description('Define and validate a parity-gated vertical migration slice');
+migrationSlice
+    .command('init')
+    .requiredOption('--ledger <path>', 'Review ledger path')
+    .requiredOption('--tag <tag>', 'Stable slice tag')
+    .requiredOption('--name <name>', 'Slice display name')
+    .requiredOption('--files <path>', 'JSON array of repository-relative slice files')
+    .option('--output <path>', 'Slice manifest output path')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationSliceInit({ ...opts, json: Boolean(opts.json) })));
+migrationSlice
+    .command('define')
+    .requiredOption('--slice <path>', 'Migration slice manifest path')
+    .requiredOption('--data <path>', 'JSON file containing contracts, parity requirements, assets, tests, and cutover controls')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationSliceDefine({
+    slice: opts.slice,
+    data: opts.data,
+    json: Boolean(opts.json),
+})));
+migrationSlice
+    .command('validate')
+    .requiredOption('--slice <path>', 'Migration slice manifest path')
+    .option('--strict', 'Fail unless review, parity, assets, tests, cutover, and rollback are complete')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationSliceValidate({
+    slice: opts.slice,
+    strict: Boolean(opts.strict),
+    json: Boolean(opts.json),
+})));
+const migrationPortfolio = program
+    .command('migration-portfolio')
+    .description('Partition and validate a large migration across bounded AI contexts');
+migrationPortfolio
+    .command('propose')
+    .requiredOption('--ledger <path>', 'Review ledger with contextual internal references')
+    .option('--max-bytes <bytes>', 'Maximum estimated bytes per proposed partition', '128000')
+    .option('--max-tokens <tokens>', 'Maximum estimated tokens per proposed partition', '32000')
+    .option('--output <path>', 'Advisory proposal output path')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationPortfolioPropose({
+    ledger: opts.ledger,
+    maxBytes: Number(opts.maxBytes),
+    maxTokens: Number(opts.maxTokens),
+    output: opts.output,
+    json: Boolean(opts.json),
+})));
+migrationPortfolio
+    .command('init')
+    .requiredOption('--ledger <path>', 'Review ledger path')
+    .requiredOption('--definition <path>', 'JSON definition containing partitions, slices, and cross-slice contracts')
+    .option('--output <path>', 'Portfolio output path')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationPortfolioInit({ ...opts, json: Boolean(opts.json) })));
+migrationPortfolio
+    .command('validate')
+    .requiredOption('--portfolio <path>', 'Migration portfolio path')
+    .option('--strict', 'Fail unless partitions, provenance, slices, and cross-slice contracts are complete')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runMigrationPortfolioValidate({
+    portfolio: opts.portfolio,
+    strict: Boolean(opts.strict),
+    json: Boolean(opts.json),
+})));
+const migrationDatabase = program.command('migration-database').description('Validate database baseline, data movement, and cutover evidence');
+migrationDatabase.command('init').requiredOption('--definition <path>').requiredOption('--output <path>').option('--json')
+    .action(wrap((opts) => runMigrationDatabaseInit({ ...opts, json: Boolean(opts.json) })));
+migrationDatabase.command('validate').requiredOption('--directory <path>').option('--strict').option('--json')
+    .action(wrap((opts) => runMigrationDatabaseValidate({ ...opts, strict: Boolean(opts.strict), json: Boolean(opts.json) })));
+program.command('migration-environments')
+    .description('Reconcile detected environments with an authenticated product environment inventory')
+    .requiredOption('--analysis <path>')
+    .requiredOption('--inventory <path>')
+    .option('--strict')
+    .option('--json')
+    .action(wrap((opts) => runMigrationEnvironmentsReconcile({
+    ...opts, strict: Boolean(opts.strict), json: Boolean(opts.json),
+})));
+const migrationProducts = program.command('migration-products')
+    .description('Validate monorepo service ownership, product mapping, asset environment coverage, and promotion');
+migrationProducts.command('init')
+    .requiredOption('--analysis <path>').requiredOption('--definition <path>').requiredOption('--output <path>')
+    .option('--json').action(wrap((opts) => runMigrationProductsInit({ ...opts, json: Boolean(opts.json) })));
+migrationProducts.command('validate')
+    .requiredOption('--file <path>').option('--strict').option('--json')
+    .action(wrap((opts) => runMigrationProductsValidate({
+    ...opts, strict: Boolean(opts.strict), json: Boolean(opts.json),
+})));
+const migrationSecrets = program.command('migration-secrets')
+    .description('Classify and reconcile names-only secret references and rotation plans');
+migrationSecrets.command('init')
+    .requiredOption('--analysis <path>').requiredOption('--definition <path>').requiredOption('--output <path>')
+    .option('--json').action(wrap((opts) => runMigrationSecretsInit({ ...opts, json: Boolean(opts.json) })));
+migrationSecrets.command('validate')
+    .requiredOption('--file <path>').option('--strict').option('--json')
+    .action(wrap((opts) => runMigrationSecretsValidate({
+    ...opts, strict: Boolean(opts.strict), json: Boolean(opts.json),
+})));
 const APPLY_TYPES = ['sessions', 'notifications', 'events'];
 program
     .command('apply')
@@ -210,13 +553,25 @@ productComponents
     .action(wrap((opts) => runProductComponents('get', opts)));
 const productEnvironments = products
     .command('environments')
-    .description('Product environments (list, get)');
+    .description('Product environments (list, get, idempotent create, update)');
 productEnvironments
     .command('list [product_tag]')
     .description('List all environments for a product')
     .option('--product <tag>', 'Product tag (defaults to linked project)')
     .option('--json', 'JSON output')
     .action(wrap((productTagArg, opts) => runProductEnvironments('list', { product: opts.product ?? productTagArg, json: opts.json }, [])));
+productEnvironments
+    .command('create <product_tag>')
+    .description('Idempotently create a product environment and verify persistence')
+    .requiredOption('-f, --file <path>', 'Environment JSON: env_name, description, slug, active?')
+    .option('--json', 'JSON output')
+    .action(wrap((productTag, opts) => runProductEnvironments('create', { product: productTag, file: opts.file, json: opts.json }, [])));
+productEnvironments
+    .command('update <product_tag> <slug>')
+    .description('Update a product environment and verify persistence')
+    .requiredOption('-f, --file <path>', 'Environment patch JSON')
+    .option('--json', 'JSON output')
+    .action(wrap((productTag, slug, opts) => runProductEnvironments('update', { product: productTag, slug, file: opts.file, json: opts.json }, [])));
 productEnvironments
     .command('get <product_tag> [slug]')
     .description('Fetch a single product environment by slug')
@@ -369,6 +724,23 @@ program
     .option('--no-interactive', 'Require -f JSON for create/update')
     .option('--json', 'JSON output')
     .action(wrap((verb, opts) => runSecrets(verb, opts)));
+program
+    .command('secrets-import-env')
+    .description('Import one secret directly from a local .env file without placing its value in CLI arguments')
+    .requiredOption('--env-file <path>', 'Local environment file')
+    .requiredOption('--source-key <name>', 'Environment variable name to read')
+    .option('-k, --key <key>', 'Destination Ductape secret key; defaults to source key')
+    .option('--env <slug>', 'Ductape environment scope')
+    .option('--description <text>')
+    .option('--json', 'Redacted JSON output')
+    .action(wrap((opts) => runSecretImportEnv({
+    envFile: opts.envFile,
+    sourceKey: opts.sourceKey,
+    key: opts.key,
+    env: opts.env,
+    description: opts.description,
+    json: Boolean(opts.json),
+})));
 const generate = program.command('generate').description('Payload templates & code snippets');
 generate
     .command('payload <family> <method>')

package/dist/lib/migration-artifact.d.ts

@@ -0,0 +1,19 @@
+export type MigrationArtifactErrorCode = 'ARTIFACT_TOO_LARGE' | 'ARTIFACT_INVALID_JSON' | 'ARTIFACT_SECRET_MATERIAL' | 'ARTIFACT_LOCKED' | 'ARTIFACT_EXISTS' | 'ARTIFACT_VERSION_UNSUPPORTED' | 'ARTIFACT_RECOVERY_FAILED';
+export declare const MIGRATION_ERROR_CODES: {
+    readonly validation: "MIGRATION_VALIDATION_FAILED";
+    readonly configuration: "MIGRATION_CONFIGURATION_INVALID";
+    readonly external: "MIGRATION_EXTERNAL_OPERATION_FAILED";
+};
+export declare function structuredMigrationError(error: unknown): string;
+export declare class MigrationArtifactError extends Error {
+    readonly code: MigrationArtifactErrorCode;
+    constructor(code: MigrationArtifactErrorCode, message: string);
+}
+export declare function readMigrationJson<T>(file: string, maxBytes?: number): T;
+export declare function writeMigrationJson(file: string, value: unknown, opts?: {
+    createOnly?: boolean;
+    backup?: boolean;
+    mode?: number;
+}): void;
+export declare function recoverMigrationJson(file: string): void;
+export declare function migrateMigrationJson(file: string, output: string): void;

package/dist/lib/migration-artifact.js

@@ -0,0 +1,114 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export const MIGRATION_ERROR_CODES = {
+    validation: 'MIGRATION_VALIDATION_FAILED',
+    configuration: 'MIGRATION_CONFIGURATION_INVALID',
+    external: 'MIGRATION_EXTERNAL_OPERATION_FAILED',
+};
+export function structuredMigrationError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/^\[[A-Z0-9_]+\]/.test(message))
+        return message;
+    return `[${MIGRATION_ERROR_CODES.validation}] ${message}`;
+}
+export class MigrationArtifactError extends Error {
+    code;
+    constructor(code, message) {
+        super(`[${code}] ${message}`);
+        this.code = code;
+        this.name = 'MigrationArtifactError';
+    }
+}
+const SECRET_KEY = /^(?:value|password|passwd|token|access_key|accesskey|private_key|credential|client_secret)$/i;
+const SECRET_VALUE = /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|(?:^|\s)eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}|[a-z][a-z0-9+.-]*:\/\/[^/\s:@]+:[^/\s@]+@/i;
+const SAFE_PLACEHOLDER = /^\[(?:REDACTED|NOT_READ|NOT_RETURNED)\]$|^\$Secret\{[^}]+\}$/;
+function inspect(value, location = '$') {
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => inspect(item, `${location}[${index}]`));
+        return;
+    }
+    if (!value || typeof value !== 'object')
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        const childLocation = `${location}.${key}`;
+        if (typeof child === 'string' &&
+            ((SECRET_KEY.test(key) && child.trim() && !SAFE_PLACEHOLDER.test(child)) || SECRET_VALUE.test(child))) {
+            throw new MigrationArtifactError('ARTIFACT_SECRET_MATERIAL', `Potential secret material or value-bearing field is forbidden at ${childLocation}; store only a name or $Secret{tag} reference.`);
+        }
+        inspect(child, childLocation);
+    }
+}
+export function readMigrationJson(file, maxBytes = 5_000_000) {
+    const resolved = path.resolve(file);
+    const stats = fs.statSync(resolved);
+    if (stats.size > maxBytes) {
+        throw new MigrationArtifactError('ARTIFACT_TOO_LARGE', `${resolved} exceeds ${maxBytes} bytes.`);
+    }
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(resolved, 'utf8'));
+    }
+    catch {
+        throw new MigrationArtifactError('ARTIFACT_INVALID_JSON', `${resolved}: JSON parsing failed; parser context is intentionally suppressed to prevent evidence leakage.`);
+    }
+    inspect(value);
+    return value;
+}
+export function writeMigrationJson(file, value, opts = {}) {
+    inspect(value);
+    const resolved = path.resolve(file);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    const lock = `${resolved}.lock`;
+    let descriptor;
+    try {
+        try {
+            descriptor = fs.openSync(lock, 'wx');
+        }
+        catch (error) {
+            if (error.code === 'EEXIST') {
+                throw new MigrationArtifactError('ARTIFACT_LOCKED', `${resolved} is being written by another process.`);
+            }
+            throw error;
+        }
+        if (opts.createOnly && fs.existsSync(resolved)) {
+            throw new MigrationArtifactError('ARTIFACT_EXISTS', `${resolved} already exists.`);
+        }
+        if (opts.backup && fs.existsSync(resolved)) {
+            fs.copyFileSync(resolved, `${resolved}.bak`);
+        }
+        const temporary = `${resolved}.tmp-${process.pid}-${Date.now()}`;
+        fs.writeFileSync(temporary, JSON.stringify(value, null, 2) + '\n', { mode: opts.mode });
+        fs.renameSync(temporary, resolved);
+    }
+    finally {
+        if (descriptor !== undefined) {
+            fs.closeSync(descriptor);
+            if (fs.existsSync(lock))
+                fs.unlinkSync(lock);
+        }
+    }
+}
+export function recoverMigrationJson(file) {
+    const resolved = path.resolve(file);
+    const backup = `${resolved}.bak`;
+    try {
+        readMigrationJson(backup);
+        fs.copyFileSync(backup, resolved);
+        readMigrationJson(resolved);
+    }
+    catch (error) {
+        throw new MigrationArtifactError('ARTIFACT_RECOVERY_FAILED', error instanceof Error ? error.message : String(error));
+    }
+}
+export function migrateMigrationJson(file, output) {
+    const value = readMigrationJson(file);
+    if (value.version === 1) {
+        writeMigrationJson(output, value, { createOnly: true });
+        return;
+    }
+    if (value.version === 0 && typeof value.artifact_kind === 'string') {
+        writeMigrationJson(output, { ...value, version: 1, migrated_from_version: 0 }, { createOnly: true });
+        return;
+    }
+    throw new MigrationArtifactError('ARTIFACT_VERSION_UNSUPPORTED', `No controlled migration exists for version ${String(value.version)}.`);
+}

package/package.json

@@ -1,12 +1,19 @@
 {
   "name": "@ductape/cli",
-  "version": "0.2.23",
+  "version": "0.3.1",
   "description": "Ductape CLI — local platform, login, link projects, and manage resources via the proxy (Workbench-compatible)",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
     "ductape": "dist/index.js"
   },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "CHANGELOG.md",
+    ".env.ductape.example"
+  ],
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/index.ts",

package/API_PARITY.md

@@ -1,58 +0,0 @@
-# CLI ↔ API parity (Nest / Workbench)
-
-The CLI uses the **same REST paths as the Workbench and TypeScript SDK**.
-
-| Profile | `api_url` | Example login URL |
-|---------|-----------|-------------------|
-| `cloud` | `https://api.ductape.app` | `https://api.ductape.app/users/v1/login` |
-| `local` | `http://localhost:4311/api` | `http://localhost:4311/api/users/v1/login` |
-
-Production does **not** use an `/api` prefix; the local docker gateway does.
-
-## Gateway routing
-
-| Client calls | Gateway (`/api/...`) | Nest service receives |
-|--------------|----------------------|------------------------|
-| `{api}/users/v1/login` | `/api/users/` → users:8002 | `/users/v1/login` |
-| `{api}/workspaces/v1/fetch/...` | `/api/workspaces/` → workspaces:8001 | `/workspaces/v1/...` |
-| `{api}/apps/v1/import` | `/api/apps/` → apps:8004 | `/apps/v1/import` |
-| `{api}/integrations/v1/create` | `/api/integrations/` → integrations:8009 | `/integrations/v1/create` |
-| `{api}/proxy/v1/sdk-proxy/execute` | `/api/proxy/` → proxy:8020 | encrypted sdk-proxy |
-
-Legacy Express services are **not** called by the CLI. All commands target Nest controllers under `platform/nest/apps/*/src/**/controllers/`.
-
-## Command → endpoint map
-
-| CLI | Method | Path (after `{api_url}`) | Workbench equivalent |
-|-----|--------|---------------------------|-------------------|
-| `ductape login` | POST | `/users/v1/login` | Login modal |
-| `ductape workspaces list` | GET | `/workspaces/v1/fetch/:user_id` | Workspace list |
-| `ductape products list` | GET | `/integrations/v1/workspace/:id/:status` | Products sidebar |
-| `ductape products create` | POST | `/integrations/v1/create` | Create product |
-| `ductape products update` | sdk-proxy | `product.update` | Product settings |
-| `ductape products delete` | DELETE | `/integrations/v1/:id` | Delete product |
-| `ductape apps list` | GET | `/apps/v1/workspace/:id/:status` | Apps sidebar |
-| `ductape apps create` | POST | `/apps/v1/create` | Create app |
-| `ductape apps import` | POST multipart | `/apps/v1/import` | App import dialog |
-| `ductape apps update` | PUT | `/apps/v1/:app_id` | App settings |
-| `ductape apps delete` | DELETE | `/apps/v1/:app_id` | Delete app |
-| `ductape resources *` | POST | `/proxy/v1/sdk-proxy/execute` | SDK proxy (encrypted) |
-| `ductape db *` | POST | `/proxy/v1/db-proxy/...` | Database proxy |
-| `ductape graph *` | POST | `/proxy/v1/graph-proxy/...` | Graph proxy |
-
-## Import body fields (`apps import`)
-
-Matches `AppsImportController` and `@ductape/sdk` `AppApiService.importApp`:
-
-| Field | CLI / SDK value |
-|-------|-----------------|
-| `type` | `PostmanV2.1` or `OpenApiV3.0` |
-| `version` | default `0.0.1` |
-| `update` | `true` / `false` |
-| `workspace_id`, `user_id`, `public_key` | from session |
-| `app_id` | optional (`--app-id` / `--app-tag`) |
-| `file` | multipart upload |
-
-## SDK base URL note
-
-The TS SDK client uses host `https://api.ductape.app` with paths like `/apps/v1/...` (no `/api` segment). Production routing may terminate TLS at a layer that forwards directly to services. **CLI and Workbench** use `{host}/api` as `api_url` — always set `ductape profiles use local` to `http://localhost:4311/api` for local parity.