@ductape/cli 0.3.35 → 0.4.0

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

@@ -1,6 +1,9 @@
 export interface FeaturesSyncOpts {
     filter?: string;
 }
+export interface FeaturesValidateOpts {
+    json?: boolean;
+}
 export declare const DUCTAPE_CATALOGUE_SYNC_ENV = "DUCTAPE_SYNC_MODE";
 export declare const DUCTAPE_FEATURE_FILTER_ENV = "DUCTAPE_FEATURE_FILTER";
 export declare function buildFeaturesSyncEnvironment(filter?: string, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
@@ -8,8 +11,10 @@ export declare function buildFeaturesSyncEnvironment(filter?: string, base?: Nod
  * 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"
+ * cannot safely execute that code in isolation — so, after a fail-closed AST preflight, 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>;
+export declare function runFeaturesValidate(opts?: FeaturesValidateOpts): Promise<void>;

package/dist/commands/features-sync.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { findProjectConfig } from '../lib/config.js';
 import { fail } from '../lib/output.js';
+import { formatFeatureValidation, validateFeatureProject } from '../lib/feature-control-flow.js';
 export const DUCTAPE_CATALOGUE_SYNC_ENV = 'DUCTAPE_SYNC_MODE';
 export const DUCTAPE_FEATURE_FILTER_ENV = 'DUCTAPE_FEATURE_FILTER';
 export function buildFeaturesSyncEnvironment(filter, base = process.env) {
@@ -21,7 +22,8 @@ Ductape convention for code-first Features:
      (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.
+  4. Run \`ductape features validate\`, fix every diagnostic, then run
+     \`ductape features sync\` explicitly — never automatically on app boot.
 
 The CLI sets DUCTAPE_SYNC_MODE=1 for the child process. Ductape framework integrations use this
 official catalogue-only signal to skip serving-time consumers and provider readiness. Project
@@ -36,7 +38,8 @@ 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"
+ * cannot safely execute that code in isolation — so, after a fail-closed AST preflight, 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.
  */
@@ -58,6 +61,10 @@ export async function runFeaturesSync(opts) {
         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 validation = validateFeatureProject(dir);
+    if (!validation.ok) {
+        fail(`${formatFeatureValidation(validation)}\nNo Feature registration process was started.`);
+    }
     const npmArgs = ['run', 'features:sync'];
     if (opts.filter)
         npmArgs.push('--', opts.filter);
@@ -71,3 +78,15 @@ export async function runFeaturesSync(opts) {
         fail(`features:sync exited with code ${result.status ?? 1}.`);
     }
 }
+export async function runFeaturesValidate(opts = {}) {
+    const found = findProjectConfig();
+    if (!found)
+        fail('No linked project. Run `ductape link` from your project directory (or `ductape init`).');
+    const result = validateFeatureProject(found.dir);
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatFeatureValidation(result));
+    if (!result.ok)
+        process.exitCode = 1;
+}

package/dist/commands/sessions-validate.d.ts

@@ -0,0 +1,3 @@
+export declare function runSessionsValidate(opts?: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/sessions-validate.js

@@ -0,0 +1,12 @@
+import { findProjectConfig } from '../lib/config.js';
+import { fail } from '../lib/output.js';
+import { formatSessionConformance, validateSessionConformance } from '../lib/session-conformance.js';
+export async function runSessionsValidate(opts = {}) {
+    const found = findProjectConfig();
+    if (!found)
+        fail('No linked project. Run `ductape link` from your project directory (or `ductape init`).');
+    const result = validateSessionConformance(found.dir);
+    console.log(opts.json ? JSON.stringify(result, null, 2) : formatSessionConformance(result));
+    if (!result.ok)
+        process.exitCode = 1;
+}

package/dist/index.js

@@ -18,7 +18,8 @@ import { runCloud, runCloudPreflight } from './commands/cloud.js';
 import { runDb, runDbActions, runDbContext } from './commands/db.js';
 import { runComponentActions } from './commands/component-actions.js';
 import { runDbMigrate, runDbMigrateStatus, runDbMigrateRollback } from './commands/db-migrate.js';
-import { runFeaturesSync } from './commands/features-sync.js';
+import { runFeaturesSync, runFeaturesValidate } from './commands/features-sync.js';
+import { runSessionsValidate } from './commands/sessions-validate.js';
 import { runDbSchemaGenerate, runDbSchemaPush } from './commands/db-schema.js';
 import { runGraph } from './commands/graph.js';
 import { runSecretImportEnv, runSecrets } from './commands/secrets.js';
@@ -895,10 +896,22 @@ db
     return runDb(verb, { file: opts.file, json: opts.json });
 }));
 const features = program.command('features').description('Code-first Ductape Features (ductape/features/)');
+const sessions = program.command('sessions').description('Session lifecycle and propagation checks');
+sessions
+    .command('validate')
+    .description('Read-only project-wide audit of Ductape SDK session propagation')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runSessionsValidate({ json: Boolean(opts.json) })));
+features
+    .command('validate')
+    .description('Read-only AST validation of code-first Feature control flow; performs no remote mutation')
+    .option('--json', 'JSON output')
+    .action(wrap((opts) => runFeaturesValidate({ json: Boolean(opts.json) })));
 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). ' +
+    '"features:sync" npm script after a fail-closed AST validation preflight ' +
+    '(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 })));

package/dist/lib/feature-control-flow.d.ts

@@ -0,0 +1,18 @@
+export type FeatureControlFlowDiagnostic = {
+    file: string;
+    line: number;
+    column: number;
+    feature?: string;
+    code: string;
+    message: string;
+};
+export type FeatureProjectValidation = {
+    ok: boolean;
+    projectRoot: string;
+    featuresDir: string;
+    filesScanned: number;
+    featuresFound: number;
+    diagnostics: FeatureControlFlowDiagnostic[];
+};
+export declare function validateFeatureProject(projectRoot: string): FeatureProjectValidation;
+export declare function formatFeatureValidation(result: FeatureProjectValidation): string;

package/dist/lib/feature-control-flow.js

@@ -0,0 +1,189 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from '@babel/parser';
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mts', '.cts', '.mjs', '.cjs']);
+const NATIVE_NODES = new Map([
+    ['IfStatement', ['FEATURE_NATIVE_IF', 'Replace native if/else with ctx.branch(ctx.when.*, { then, else }).']],
+    ['ConditionalExpression', ['FEATURE_NATIVE_TERNARY', 'Replace the native ternary with ctx.branch().']],
+    ['SwitchStatement', ['FEATURE_NATIVE_SWITCH', 'Replace the native switch with explicit ctx.branch() paths.']],
+    ['ForStatement', ['FEATURE_NATIVE_LOOP', 'Move runtime-sized iteration into ctx.functions.']],
+    ['ForInStatement', ['FEATURE_NATIVE_LOOP', 'Move runtime-sized iteration into ctx.functions.']],
+    ['ForOfStatement', ['FEATURE_NATIVE_LOOP', 'Move runtime-sized iteration into ctx.functions.']],
+    ['WhileStatement', ['FEATURE_NATIVE_LOOP', 'Move runtime-sized iteration into ctx.functions.']],
+    ['DoWhileStatement', ['FEATURE_NATIVE_LOOP', 'Move runtime-sized iteration into ctx.functions.']],
+]);
+const COLLECTION_METHODS = new Set(['map', 'filter', 'find', 'findIndex', 'some', 'every', 'reduce', 'reduceRight', 'forEach']);
+function propertyName(node) {
+    if (!node)
+        return undefined;
+    if (!node.computed && node.key?.type === 'Identifier')
+        return node.key.name;
+    if (node.key?.type === 'StringLiteral')
+        return node.key.value;
+    return undefined;
+}
+function memberName(node) {
+    if (!node || (node.type !== 'MemberExpression' && node.type !== 'OptionalMemberExpression'))
+        return undefined;
+    if (!node.computed && node.property?.type === 'Identifier')
+        return node.property.name;
+    if (node.computed && node.property?.type === 'StringLiteral')
+        return node.property.value;
+    return undefined;
+}
+function memberPath(node) {
+    if (node?.type === 'Identifier')
+        return [node.name];
+    if (node?.type !== 'MemberExpression' && node?.type !== 'OptionalMemberExpression')
+        return [];
+    const property = memberName(node);
+    return [...memberPath(node.object), ...(property ? [property] : [])];
+}
+function isFeatureDefineCall(node) {
+    if (node?.type !== 'CallExpression' && node?.type !== 'OptionalCallExpression')
+        return false;
+    const parts = memberPath(node.callee);
+    if (parts.at(-1) !== 'define')
+        return false;
+    return parts.some((part) => ['feature', 'features', 'workflow', 'workflows'].includes(part));
+}
+function literalString(node) {
+    return node?.type === 'StringLiteral' ? node.value : undefined;
+}
+function isMemberPath(node, objectName, propertyName) {
+    return (node?.type === 'MemberExpression' || node?.type === 'OptionalMemberExpression') &&
+        node.object?.type === 'Identifier' && node.object.name === objectName && memberName(node) === propertyName;
+}
+function sourceFiles(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    const output = [];
+    const visit = (current) => {
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'build')
+                continue;
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory())
+                visit(full);
+            else if (SOURCE_EXTENSIONS.has(path.extname(entry.name)))
+                output.push(full);
+        }
+    };
+    visit(dir);
+    return output.sort();
+}
+export function validateFeatureProject(projectRoot) {
+    const root = path.resolve(projectRoot);
+    const featuresDir = path.join(root, 'ductape', 'features');
+    const files = sourceFiles(featuresDir);
+    const diagnostics = [];
+    let featuresFound = 0;
+    const add = (file, node, feature, code, message) => {
+        diagnostics.push({
+            file: path.relative(root, file),
+            line: node.loc?.start.line ?? 1,
+            column: (node.loc?.start.column ?? 0) + 1,
+            feature,
+            code,
+            message,
+        });
+    };
+    for (const file of files) {
+        let ast;
+        try {
+            ast = parse(fs.readFileSync(file, 'utf8'), {
+                sourceType: 'unambiguous',
+                plugins: ['typescript', 'jsx', ['decorators', { decoratorsBeforeExport: true }]],
+            });
+        }
+        catch (error) {
+            diagnostics.push({
+                file: path.relative(root, file), line: 1, column: 1,
+                code: 'FEATURE_SOURCE_PARSE_ERROR',
+                message: error instanceof Error ? error.message : String(error),
+            });
+            continue;
+        }
+        const visit = (node, active) => {
+            if (!node || typeof node !== 'object')
+                return;
+            if (!active && isFeatureDefineCall(node) && node.arguments?.[0]?.type !== 'ObjectExpression') {
+                add(file, node, undefined, 'FEATURE_DYNAMIC_DEFINITION_UNINSPECTED', 'The validator cannot inspect a dynamically supplied Feature definition. Inline the definition object before syncing.');
+            }
+            if (node.type === 'ObjectExpression') {
+                const props = new Map();
+                for (const property of node.properties ?? []) {
+                    if (property.type === 'ObjectProperty' || property.type === 'ObjectMethod') {
+                        const name = propertyName(property);
+                        if (name)
+                            props.set(name, property);
+                    }
+                }
+                const handlerProp = props.get('handler');
+                if (handlerProp && props.has('tag')) {
+                    featuresFound += 1;
+                    const tag = literalString(props.get('tag')?.value);
+                    const mode = literalString(props.get('controlFlowMode')?.value) === 'legacy' ? 'legacy' : 'portable';
+                    if (mode !== 'legacy') {
+                        for (const legacyKey of ['branchOverrides', 'recordScenarios']) {
+                            const legacy = props.get(legacyKey);
+                            if (legacy)
+                                add(file, legacy, tag, 'FEATURE_LEGACY_RECORDING_OPTION', `${legacyKey} requires controlFlowMode: 'legacy'.`);
+                        }
+                    }
+                    const handler = handlerProp.type === 'ObjectMethod' ? handlerProp : handlerProp.value;
+                    if (!['ObjectMethod', 'ArrowFunctionExpression', 'FunctionExpression'].includes(handler?.type)) {
+                        add(file, handlerProp, tag, 'FEATURE_EXTERNAL_HANDLER_UNINSPECTED', 'The validator cannot inspect a referenced handler. Inline the handler in the Feature definition before syncing.');
+                        return;
+                    }
+                    visit(handler, { tag, mode });
+                    return;
+                }
+            }
+            if (active) {
+                if (active.mode === 'portable') {
+                    const native = NATIVE_NODES.get(node.type);
+                    if (native)
+                        add(file, node, active.tag, native[0], native[1]);
+                    if (node.type === 'LogicalExpression') {
+                        add(file, node, active.tag, 'FEATURE_NATIVE_LOGICAL_BRANCH', `Native "${node.operator}" short-circuiting runs during recording; use ctx.branch(), ctx.when, or ctx.default().`);
+                    }
+                    if ((node.type === 'CallExpression' || node.type === 'OptionalCallExpression') &&
+                        COLLECTION_METHODS.has(memberName(node.callee) ?? '')) {
+                        add(file, node, active.tag, 'FEATURE_NATIVE_COLLECTION_CONTROL_FLOW', `Native .${memberName(node.callee)}() is not portable runtime collection logic; use ctx.functions.`);
+                    }
+                }
+                if (node.type === 'CallExpression' || node.type === 'OptionalCallExpression') {
+                    if (isMemberPath(node.callee, 'Date', 'now'))
+                        add(file, node, active.tag, 'FEATURE_HOST_TIME', 'Use ctx.transform.now().');
+                    if (isMemberPath(node.callee, 'Math', 'random'))
+                        add(file, node, active.tag, 'FEATURE_HOST_RANDOM', 'Use a portable function or reusable action.');
+                    if (memberName(node.callee) === 'randomUUID')
+                        add(file, node, active.tag, 'FEATURE_HOST_UUID', 'Use ctx.transform.uuid().');
+                }
+                if ((node.type === 'MemberExpression' || node.type === 'OptionalMemberExpression') &&
+                    isMemberPath(node.object, 'process', 'env')) {
+                    add(file, node, active.tag, 'FEATURE_HOST_ENVIRONMENT', 'Use Ductape runtime configuration instead of process.env.');
+                }
+            }
+            for (const [key, value] of Object.entries(node)) {
+                if (key === 'loc' || key === 'start' || key === 'end' || key === 'extra')
+                    continue;
+                if (Array.isArray(value))
+                    value.forEach((child) => visit(child, active));
+                else if (value && typeof value === 'object')
+                    visit(value, active);
+            }
+        };
+        visit(ast);
+    }
+    diagnostics.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column);
+    return { ok: diagnostics.length === 0, projectRoot: root, featuresDir, filesScanned: files.length, featuresFound, diagnostics };
+}
+export function formatFeatureValidation(result) {
+    if (result.ok) {
+        return `Feature control-flow validation passed (${result.featuresFound} features in ${result.filesScanned} files).`;
+    }
+    const lines = result.diagnostics.map((item) => `${item.file}:${item.line}:${item.column} ${item.code}${item.feature ? ` [${item.feature}]` : ''}: ${item.message}`);
+    return `Feature control-flow validation failed with ${result.diagnostics.length} error(s):\n${lines.join('\n')}`;
+}

package/dist/lib/session-conformance.d.ts

@@ -0,0 +1,16 @@
+export type SessionClassification = 'explicit' | 'inherited' | 'delegated' | 'system' | 'missing';
+export interface SessionFinding {
+    file: string;
+    line: number;
+    call: string;
+    classification: SessionClassification;
+    reason?: string;
+}
+export interface SessionValidationResult {
+    ok: boolean;
+    root: string;
+    summary: Record<SessionClassification | 'calls', number>;
+    findings: SessionFinding[];
+}
+export declare function validateSessionConformance(rootDir: string): SessionValidationResult;
+export declare function formatSessionConformance(result: SessionValidationResult): string;

package/dist/lib/session-conformance.js

@@ -0,0 +1,82 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+const IGNORED = new Set(['.git', 'dist', 'build', 'coverage', 'node_modules']);
+const CALL = /\b(?:ductape\.)?(api|feature|database|databases|graph|vector|storage|events|notifications|quota|fallback)\.([A-Za-z_$][\w$]*)\s*\(/g;
+function walk(root, files) {
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+        if (entry.isSymbolicLink() || IGNORED.has(entry.name))
+            continue;
+        const target = path.join(root, entry.name);
+        if (entry.isDirectory())
+            walk(target, files);
+        else if (EXTENSIONS.has(path.extname(entry.name)))
+            files.push(target);
+    }
+}
+function invocation(source, open) {
+    let depth = 0;
+    let quote = '';
+    let escaped = false;
+    for (let i = open; i < source.length; i += 1) {
+        const char = source[i];
+        if (quote) {
+            if (escaped)
+                escaped = false;
+            else if (char === '\\')
+                escaped = true;
+            else if (char === quote)
+                quote = '';
+            continue;
+        }
+        if (char === '"' || char === "'" || char === '`') {
+            quote = char;
+            continue;
+        }
+        if (char === '(')
+            depth += 1;
+        if (char === ')' && --depth === 0)
+            return source.slice(open + 1, i);
+    }
+    return source.slice(open + 1);
+}
+export function validateSessionConformance(rootDir) {
+    const root = path.resolve(rootDir);
+    const files = [];
+    walk(root, files);
+    const findings = [];
+    for (const file of files) {
+        const source = fs.readFileSync(file, 'utf8');
+        let match;
+        while ((match = CALL.exec(source))) {
+            const call = `${match[1]}.${match[2]}`;
+            const line = source.slice(0, match.index).split('\n').length;
+            const args = invocation(source, source.indexOf('(', match.index));
+            const nearby = source.slice(Math.max(0, match.index - 300), match.index);
+            let classification = 'missing';
+            let reason;
+            if (/\bsession\s*:/.test(args))
+                classification = 'explicit';
+            else if (/\bctx\.$/.test(nearby))
+                classification = 'inherited';
+            else {
+                const marker = nearby.match(/ductape-session:\s*(delegated|system)\s+([^\n]+)/i);
+                if (marker) {
+                    classification = marker[1].toLowerCase();
+                    reason = marker[2].trim();
+                }
+            }
+            findings.push({ file: path.relative(root, file).split(path.sep).join('/'), line, call, classification, reason });
+        }
+    }
+    const summary = { calls: findings.length, explicit: 0, inherited: 0, delegated: 0, system: 0, missing: 0 };
+    for (const finding of findings)
+        summary[finding.classification] += 1;
+    return { ok: summary.missing === 0, root, summary, findings };
+}
+export function formatSessionConformance(result) {
+    const lines = [`Session propagation: ${result.ok ? 'PASS' : 'FAIL'} (${result.summary.calls} calls)`];
+    for (const finding of result.findings.filter((item) => item.classification === 'missing'))
+        lines.push(`  ${finding.file}:${finding.line} ${finding.call} has no explicit, inherited, delegated, or system session classification`);
+    return lines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/cli",
-  "version": "0.3.35",
+  "version": "0.4.0",
   "description": "Ductape CLI — local platform, login, link projects, and manage resources via the proxy (Workbench-compatible)",
   "type": "module",
   "main": "dist/index.js",
@@ -26,6 +26,7 @@
   ],
   "license": "UNLICENSED",
   "dependencies": {
+    "@babel/parser": "7.28.5",
     "@inquirer/input": "^5.0.13",
     "@inquirer/password": "^5.0.13",
     "@inquirer/select": "^5.1.5",