@ductape/cli 0.3.15 → 0.3.17

package/dist/commands/cloud.d.ts

@@ -1,4 +1,9 @@
 type CloudTarget = 'connections' | 'resources' | 'tiers';
+export declare function runCloudPreflight(opts: {
+    product?: string;
+    file?: string;
+    json?: boolean;
+}): Promise<void>;
 export declare function runCloud(target: CloudTarget, verb: string, opts: {
     id?: string;
     file?: string;

package/dist/commands/cloud.js

@@ -3,6 +3,80 @@ import { getSdkProxy, requireSession } from '../lib/proxy/context.js';
 import { printJson } from '../lib/output.js';
 import { listCloudTiers } from '../lib/platform-api.js';
 import { requireWorkspaceContext } from '../lib/workspace-context.js';
+const CLOUD_SERVICE_CAPABILITIES = [
+    { service: 's3', provider: 'aws', types: ['storage'], actions: ['list', 'import', 'provision'] },
+    { service: 'gcs', provider: 'gcp', types: ['storage'], actions: ['list', 'import', 'provision'] },
+    { service: 'azure_blob', provider: 'azure', types: ['storage'], actions: ['list', 'import', 'provision'] },
+    { service: 'rds', provider: 'aws', types: ['database'], actions: ['list', 'import', 'provision'] },
+    { service: 'cloud_sql', provider: 'gcp', types: ['database'], actions: ['list', 'import', 'provision'] },
+    { service: 'azure_database', provider: 'azure', types: ['database'], actions: ['list', 'import', 'provision'] },
+    { service: 'mongodb_atlas', provider: 'mongodb_atlas', types: ['database'], actions: ['list', 'import', 'provision'] },
+    { service: 'neo4j_aura', provider: 'neo4j_aura', types: ['graph'], actions: ['list', 'import', 'provision'] },
+    { service: 'vertex_ai_vector_search', provider: 'gcp', types: ['vector'], actions: ['list', 'import', 'provision'] },
+    { service: 'opensearch', provider: 'aws', types: ['vector'], actions: ['list', 'import', 'provision'] },
+    { service: 'pubsub', provider: 'gcp', types: ['messageBroker'], actions: ['list', 'import', 'provision'] },
+    { service: 'sns_sqs', provider: 'aws', types: ['messageBroker'], actions: ['list', 'import', 'provision'] },
+];
+export async function runCloudPreflight(opts) {
+    const session = requireSession();
+    const proxy = getSdkProxy(session);
+    const product = opts.product ?? session.project.product_tag;
+    const input = readJsonBody(opts.file);
+    const [connectionsResult, environmentsResult] = await Promise.allSettled([
+        proxy.execute('cloud', 'connections.list', []),
+        proxy.execute('product', 'environments.list', [product]),
+    ]);
+    const ctx = requireWorkspaceContext();
+    const tiersResult = await Promise.allSettled([listCloudTiers(ctx, {})]);
+    const discoveries = Array.isArray(input?.discoveries) ? input.discoveries : [];
+    const discoveryResults = await Promise.all(discoveries.map(async (request) => {
+        try {
+            return { request, ok: true, resources: await proxy.execute('cloud', 'resources.list', [request]) };
+        }
+        catch (error) {
+            return { request, ok: false, error: error instanceof Error ? error.message : String(error) };
+        }
+    }));
+    const environments = environmentsResult.status === 'fulfilled' ? environmentsResult.value : null;
+    const envList = Array.isArray(environments)
+        ? environments
+        : environments && typeof environments === 'object' && Array.isArray(environments.data)
+            ? environments.data
+            : [];
+    const inactive = envList.filter((env) => env && typeof env === 'object' && env.active === false);
+    const unresolved = [];
+    if (connectionsResult.status === 'rejected')
+        unresolved.push(`Cloud connections could not be listed: ${String(connectionsResult.reason)}`);
+    if (environmentsResult.status === 'rejected')
+        unresolved.push(`Product environments could not be listed: ${String(environmentsResult.reason)}`);
+    if (tiersResult[0].status === 'rejected')
+        unresolved.push(`Cloud tiers could not be listed: ${String(tiersResult[0].reason)}`);
+    if (discoveries.length === 0)
+        unresolved.push('No instance discovery requests supplied; pass --file with {"discoveries":[{cloud,service,type,...}]}.');
+    if (inactive.length > 0)
+        unresolved.push('Inactive environments still require an explicit configuration decision; preflight does not assume shared or provisioned infrastructure.');
+    for (const result of discoveryResults)
+        if (!result.ok)
+            unresolved.push(`Instance discovery failed for ${String(result.request.service ?? 'unknown service')}: ${result.error}`);
+    printJson({
+        product,
+        read_only: true,
+        supported_services: CLOUD_SERVICE_CAPABILITIES,
+        required_discovery_fields: ['cloud', 'service', 'type'],
+        connections: connectionsResult.status === 'fulfilled' ? connectionsResult.value : null,
+        environments: envList,
+        inactive_environment_policy: 'explicit_configuration_required_no_automatic_provisioning',
+        tiers: tiersResult[0].status === 'fulfilled' ? tiersResult[0].value : null,
+        instances: discoveryResults,
+        mutation_actions: {
+            import_existing: ['import-persist', 'import-persist-all'],
+            provision_new: ['provision-persist', 'provision-persist-all'],
+            destructive_deprovision: false,
+        },
+        unresolved_decisions: unresolved,
+        ready: unresolved.length === 0,
+    }, Boolean(opts.json));
+}
 export async function runCloud(target, verb, opts, extraArgs) {
     if (target === 'tiers') {
         const ctx = requireWorkspaceContext();

package/dist/commands/doctor.d.ts

@@ -0,0 +1,4 @@
+export declare function runDoctor(opts: {
+    json?: boolean;
+    cliVersion: string;
+}): Promise<void>;

package/dist/commands/doctor.js

@@ -0,0 +1,123 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { findProjectConfig, getActiveProfileName, getApiUrl, loadCredentials, loadGlobalConfig, } from '../lib/config.js';
+function findUp(name, start = process.cwd()) {
+    let dir = path.resolve(start);
+    const root = path.parse(dir).root;
+    while (true) {
+        const candidate = path.join(dir, name);
+        if (fs.existsSync(candidate))
+            return candidate;
+        if (dir === root)
+            return null;
+        dir = path.dirname(dir);
+    }
+}
+function readJson(file) {
+    if (!file)
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function dependencyVersion(pkg, name) {
+    for (const key of ['dependencies', 'devDependencies', 'peerDependencies']) {
+        const values = pkg?.[key];
+        if (values && typeof values === 'object' && typeof values[name] === 'string') {
+            return values[name];
+        }
+    }
+    return null;
+}
+function configuredMcpVersion(config) {
+    const servers = config?.mcpServers;
+    if (!servers || typeof servers !== 'object')
+        return null;
+    for (const value of Object.values(servers)) {
+        if (!value || typeof value !== 'object')
+            continue;
+        const args = value.args;
+        if (!Array.isArray(args))
+            continue;
+        const spec = args.find((arg) => typeof arg === 'string' && arg.startsWith('@ductape/mcp'));
+        if (typeof spec === 'string')
+            return spec.replace(/^@ductape\/mcp@?/, '') || 'unversioned';
+    }
+    return null;
+}
+export async function runDoctor(opts) {
+    const project = findProjectConfig();
+    const profile = project?.config
+        ? getActiveProfileName(project.config)
+        : loadGlobalConfig().default_profile;
+    const apiUrl = getApiUrl(profile);
+    const credentials = loadCredentials();
+    const packageFile = findUp('package.json');
+    const pkg = readJson(packageFile);
+    const mcpFile = findUp('.mcp.json');
+    const warnings = [];
+    let schema;
+    try {
+        const response = await fetch(`${apiUrl}/proxy/v1/schema`, {
+            headers: { Accept: 'application/json' },
+            signal: AbortSignal.timeout(15_000),
+        });
+        const contentType = response.headers.get('content-type') ?? '';
+        const body = await response.text();
+        const isJson = contentType.toLowerCase().includes('json');
+        schema = {
+            reachable: response.ok && isJson,
+            status: response.status,
+            content_type: contentType,
+            revision: response.ok && isJson
+                ? `sha256:${createHash('sha256').update(body).digest('hex')}`
+                : null,
+            api_version: response.headers.get('x-api-version'),
+            request_id: response.headers.get('x-request-id') ?? response.headers.get('x-correlation-id'),
+        };
+        if (!response.ok || !isJson)
+            warnings.push(`Schema endpoint returned HTTP ${response.status} (${contentType || 'unknown content type'}).`);
+    }
+    catch (error) {
+        schema = { reachable: false, error: error instanceof Error ? error.message : String(error) };
+        warnings.push('The configured API/schema endpoint is not reachable.');
+    }
+    const versions = {
+        cli: opts.cliVersion,
+        sdk: dependencyVersion(pkg, '@ductape/sdk'),
+        nestjs: dependencyVersion(pkg, '@ductape/nestjs'),
+        mcp: configuredMcpVersion(readJson(mcpFile)),
+    };
+    if (!credentials)
+        warnings.push('Not logged in; administrative CLI operations will fail.');
+    if (!project)
+        warnings.push('No linked Ductape project was found from the current directory.');
+    if (!versions.sdk)
+        warnings.push('@ductape/sdk is not declared in the nearest package.json.');
+    if (!versions.mcp)
+        warnings.push('No @ductape/mcp package was found in the nearest .mcp.json.');
+    const result = {
+        ok: warnings.length === 0,
+        versions,
+        api: { profile, url: apiUrl, schema },
+        authentication: {
+            logged_in: Boolean(credentials),
+            user_id: credentials?.user_id ?? null,
+            email: credentials?.email ?? null,
+            active_workspace_id: loadGlobalConfig().active_workspace_id ?? null,
+        },
+        linkage: project ? { root: project.dir, ...project.config } : null,
+        sources: { package_json: packageFile, mcp_json: mcpFile },
+        warnings,
+    };
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else {
+        console.log(`Ductape doctor: ${result.ok ? 'ready' : `${warnings.length} warning(s)`}`);
+        console.log(JSON.stringify(result, null, 2));
+    }
+}

package/dist/commands/features-sync.d.ts

@@ -0,0 +1,12 @@
+export interface FeaturesSyncOpts {
+    filter?: string;
+}
+/**
+ * Persists code-first Ductape Features to the live product. Unlike `ductape db migrate` (which
+ * executes declarative migration files directly), a Feature's handler is real application code
+ * that typically depends on the app's own services (repositories, DB connections, DI). Ductape
+ * cannot safely execute that code in isolation — so this command delegates to a "features:sync"
+ * npm script that the project itself owns and controls, giving a single consistent entrypoint
+ * across every Ductape project regardless of framework.
+ */
+export declare function runFeaturesSync(opts: FeaturesSyncOpts): Promise<void>;

package/dist/commands/features-sync.js

@@ -0,0 +1,54 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { findProjectConfig } from '../lib/config.js';
+import { fail } from '../lib/output.js';
+const CONVENTION_HINT = `
+Ductape convention for code-first Features:
+  1. Define every Feature under ductape/features/ (e.g. ductape/features/src/my-feature.ts),
+     each calling ductape.feature.define({ ... }) from a registerXFeature(ductape) export.
+  2. In your app's normal startup path, register only LOCAL function/operation handlers
+     (ductape.sdk.functions.register(...)) — no network call, safe on every boot.
+  3. Add a "features:sync" script to package.json that boots just enough of your app to
+     construct real dependencies (no HTTP listener) and calls every registerXFeature(...) once.
+  4. Run it explicitly with \`ductape features sync\` — never automatically on app boot.
+
+This mirrors \`ductape db migrate\`: Features are defined in source, but persisted to the live
+product via an explicit command, so a slow or unreachable Ductape API can never block your app
+from starting.
+`;
+/**
+ * Persists code-first Ductape Features to the live product. Unlike `ductape db migrate` (which
+ * executes declarative migration files directly), a Feature's handler is real application code
+ * that typically depends on the app's own services (repositories, DB connections, DI). Ductape
+ * cannot safely execute that code in isolation — so this command delegates to a "features:sync"
+ * npm script that the project itself owns and controls, giving a single consistent entrypoint
+ * across every Ductape project regardless of framework.
+ */
+export async function runFeaturesSync(opts) {
+    const found = findProjectConfig();
+    if (!found)
+        fail('No linked project. Run `ductape link` from your project directory (or `ductape init`).');
+    const { dir } = found;
+    const packageJsonPath = path.join(dir, 'package.json');
+    if (!fs.existsSync(packageJsonPath)) {
+        fail(`No package.json found at ${dir}.\n${CONVENTION_HINT}`);
+    }
+    const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    if (!pkg.scripts?.['features:sync']) {
+        fail(`package.json at ${dir} has no "features:sync" script.\n${CONVENTION_HINT}`);
+    }
+    const featuresDir = path.join(dir, 'ductape', 'features');
+    if (!fs.existsSync(featuresDir)) {
+        console.warn(`Warning: ductape/features/ does not exist at ${dir}. Proceeding anyway — your ` +
+            '"features:sync" script may look elsewhere, but the convention is ductape/features/.');
+    }
+    const npmArgs = ['run', 'features:sync'];
+    if (opts.filter)
+        npmArgs.push('--', opts.filter);
+    console.log(`Running "npm ${npmArgs.join(' ')}" in ${dir} ...\n`);
+    const result = spawnSync('npm', npmArgs, { cwd: dir, stdio: 'inherit' });
+    if (result.status !== 0) {
+        fail(`features:sync exited with code ${result.status ?? 1}.`);
+    }
+}

package/dist/commands/resources.d.ts

@@ -25,6 +25,7 @@ export declare function runNotificationMessageCrud(verb: string, opts: {
     notification?: string;
     file?: string;
     json?: boolean;
+    product?: string;
 }): Promise<void>;
 export declare function runResourceCrud(typeName: string, verb: string, opts: {
     tag?: string;

package/dist/commands/resources.js

@@ -19,6 +19,26 @@ function unwrapArray(value) {
     }
     return undefined;
 }
+async function reconcileCreatedComponent(proxy, module, productTag, tag, timeoutMs = 20_000) {
+    const started = Date.now();
+    let attempts = 0;
+    do {
+        attempts += 1;
+        try {
+            const product = await proxy.execute('product', 'fetch', [productTag]);
+            const catalogue = listComponentsFromProduct(module, product);
+            const resource = catalogue?.find((item) => item && typeof item === 'object' && item.tag === tag);
+            if (resource)
+                return { resource, attempts, elapsed_ms: Date.now() - started };
+        }
+        catch {
+            // Preserve the original mutation error. Reconciliation is a bounded best-effort read.
+        }
+        if (Date.now() - started < timeoutMs)
+            await new Promise((resolve) => setTimeout(resolve, 2_000));
+    } while (Date.now() - started < timeoutMs);
+    return { resource: null, attempts, elapsed_ms: Date.now() - started };
+}
 /**
  * Session inventories on older platform versions can fail when the component does not exist.
  * Confirm the state through the product catalogue before treating that failure as an empty list,
@@ -210,7 +230,9 @@ export async function runNotificationMessageCrud(verb, opts) {
     }
     const session = requireSession();
     const proxy = getSdkProxy(session);
-    const product = session.project.product_tag;
+    // Explicit --product avoids silently resolving to whatever product happens to be linked in
+    // the current working directory — see resources.ts's runResourceCrud for the same pattern.
+    const product = opts.product ?? session.project.product_tag;
     const body = ['create', 'update'].includes(crud)
         ? await resolveBody({ file: opts.file, patch: crud === 'update', requireBody: crud === 'create', interactive: false })
         : undefined;
@@ -324,15 +346,25 @@ export async function runResourceCrud(typeName, verb, opts, extraArgs) {
             throw error;
         }
         try {
-            const reconciled = await proxy.execute(module, 'fetch', buildCrudParams(module, 'fetch', productTag, { tag: createdTag }));
-            if (!reconciled)
-                throw error;
-            printJson({ created: true, reconciled: true, outcome: 'succeeded_after_reconciliation', resource: reconciled }, Boolean(opts.json));
+            const reconciliation = await reconcileCreatedComponent(proxy, module, productTag, createdTag);
+            if (!reconciliation.resource) {
+                throw new DuctapeOperationError(`${error.message} Reconciliation polled the administrative product catalogue for product "${productTag}" ${reconciliation.attempts} time(s) for ${reconciliation.elapsed_ms}ms and did not find "${createdTag}". If this product tag looks wrong, pass --product explicitly instead of relying on the linked project.`, { ...error.details, code: 'MUTATION_OUTCOME_UNKNOWN', mutationState: 'unknown' });
+            }
+            printJson({
+                created: true,
+                reconciled: true,
+                outcome: 'succeeded_after_reconciliation',
+                reconciliation: { attempts: reconciliation.attempts, elapsed_ms: reconciliation.elapsed_ms },
+                resource: reconciliation.resource,
+            }, Boolean(opts.json));
             return;
         }
         catch (reconcileError) {
             if (reconcileError === error)
                 throw error;
+            if (reconcileError instanceof DuctapeOperationError && reconcileError.details.code === 'MUTATION_OUTCOME_UNKNOWN') {
+                throw reconcileError;
+            }
             throw new DuctapeOperationError(`${error.message} Reconciliation could not confirm whether "${createdTag}" exists.`, { ...error.details, code: 'MUTATION_OUTCOME_UNKNOWN', mutationState: 'unknown' }, { cause: reconcileError });
         }
     }

package/dist/index.js

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { runLogin } from './commands/login.js';
 import { runLogout } from './commands/logout.js';
 import { runWhoami } from './commands/whoami.js';
+import { runDoctor } from './commands/doctor.js';
 import { runProfilesList, runProfilesUse } from './commands/profiles.js';
 import { runLink } from './commands/link.js';
 import { runUnlink } from './commands/unlink.js';
@@ -13,9 +14,10 @@ import { runInit } from './commands/init.js';
 import { runInstall } from './commands/install.js';
 import { runStart, runStop, runStatus } from './commands/platform.js';
 import { runResourceCrud, runResourcesList, runEventTopicCrud, runNotificationMessageCrud } from './commands/resources.js';
-import { runCloud } from './commands/cloud.js';
+import { runCloud, runCloudPreflight } from './commands/cloud.js';
 import { runDb, runDbContext } from './commands/db.js';
 import { runDbMigrate, runDbMigrateStatus, runDbMigrateRollback } from './commands/db-migrate.js';
+import { runFeaturesSync } from './commands/features-sync.js';
 import { runDbSchemaGenerate, runDbSchemaPush } from './commands/db-schema.js';
 import { runGraph } from './commands/graph.js';
 import { runSecretImportEnv, runSecrets } from './commands/secrets.js';
@@ -84,6 +86,11 @@ program
     skipWorkspaceSelect: Boolean(opts.skipWorkspaceSelect),
 })));
 program.command('logout').description('Clear local credentials').action(wrap(runLogout));
+program
+    .command('doctor')
+    .description('Report CLI, SDK, MCP, API/schema, authentication, and project compatibility facts')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runDoctor({ json: Boolean(opts.json), cliVersion: pkg.version })));
 program
     .command('whoami')
     .description('Show login and linked project')
@@ -690,6 +697,7 @@ notificationMessages
     .option('-t, --tag <tag>', 'Full notification:message tag')
     .option('-n, --notification <tag>', 'Notification tag for list')
     .option('-f, --file <path>', 'JSON template body for create/update')
+    .option('--product <tag>', 'Product tag (defaults to linked project)')
     .option('--json', 'JSON output')
     .action(wrap((verb, opts) => runNotificationMessageCrud(verb, opts)));
 resources.command('types').option('--json', 'JSON output').action(wrap((opts) => runResourcesList(Boolean(opts.json))));
@@ -704,6 +712,13 @@ resources
     .option('--json', 'JSON output')
     .action(wrap((type, verb, opts) => runResourceCrud(type, verb, opts, [])));
 const cloud = program.command('cloud').description('Cloud connections & resources');
+cloud
+    .command('preflight')
+    .description('Read-only provider capability, connection, tier, instance, and environment preflight')
+    .option('--product <tag>', 'Product tag (defaults to linked project)')
+    .option('-f, --file <path>', 'Optional JSON with discovery requests')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runCloudPreflight({ product: opts.product, file: opts.file, json: opts.json })));
 cloud
     .command('connections <verb> [id]')
     .option('-f, --file <path>')
@@ -768,6 +783,14 @@ db
         throw new Error('Specify a verb: connect | query');
     return runDb(verb, { file: opts.file, json: opts.json });
 }));
+const features = program.command('features').description('Code-first Ductape Features (ductape/features/)');
+features
+    .command('sync')
+    .description('Persist Features from ductape/features/ to the live product by running the project\'s own ' +
+    '"features:sync" npm script (see `ductape features sync --help` for the required convention). ' +
+    'Run explicitly, like `ductape db migrate` — never automatically on app boot.')
+    .argument('[filter]', 'Optional substring passed through to the project\'s features:sync script')
+    .action(wrap((filter) => runFeaturesSync({ filter })));
 const graph = program.command('graph').description('Graph runtime (graph-proxy)');
 graph
     .argument('<verb>', 'connect | query | createAction | validateAction | updateAction | …')

package/dist/lib/platform-api.js

@@ -241,8 +241,16 @@ export async function connectMarketplaceApp(ctx, product, appTag, envs) {
     if (!marketplaceApp || typeof marketplaceApp !== 'object')
         throw new Error(`Marketplace app "${appTag}" was not found`);
     const app = marketplaceApp;
-    if (app.status !== 'public')
-        throw new Error(`App "${appTag}" is not public in the marketplace`);
+    // DT-021: this was a blanket "must be public" guard that also rejected an app the caller's own
+    // workspace owns and never even reaches the backend to find out whether it would allow it.
+    // ductape_marketplace_inspect has no such restriction for the same private app, so the read path
+    // already treats same-workspace ownership as sufficient — mirror that here for connect.
+    const isOwnedByCallerWorkspace = String(app.workspace_id ?? '') === String(ctx.workspaceId ?? '')
+        && Boolean(ctx.workspaceId);
+    if (app.status !== 'public' && !isOwnedByCallerWorkspace) {
+        throw new Error(`App "${appTag}" is not public in the marketplace and is not owned by your workspace. ` +
+            'Only public marketplace apps or apps your own workspace created can be connected.');
+    }
     const versions = Array.isArray(app.versions) ? app.versions : [];
     const latest = versions.find((version) => version.latest === true) ?? versions[0];
     const availableAppEnvs = new Set((Array.isArray(latest?.envs) ? latest.envs : []).map((env) => String(env && typeof env === 'object' ? env.slug ?? '' : env)).filter(Boolean));

package/dist/lib/templates.js

@@ -90,7 +90,14 @@ Docs: https://docs.ductape.app/docs/cli/
                 name: 'User session',
                 description: 'Standard authenticated user session',
                 expiry: 604800,
+                period: 'seconds',
                 refresh_expiry: 2592000,
+                refresh_period: 'seconds',
+                refresh_rotation: 'rotate_on_use',
+                selector: 'userId',
+                schema: {
+                    userId: { type: 'string', required: true },
+                },
             },
         ];
         fs.writeFileSync(sessionsPath, JSON.stringify(sessionsTemplate, null, 2) + '\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/cli",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "description": "Ductape CLI — local platform, login, link projects, and manage resources via the proxy (Workbench-compatible)",
   "type": "module",
   "main": "dist/index.js",