@ductape/cli 0.3.35 → 0.3.36

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/index.js

@@ -18,7 +18,7 @@ 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 { runDbSchemaGenerate, runDbSchemaPush } from './commands/db-schema.js';
 import { runGraph } from './commands/graph.js';
 import { runSecretImportEnv, runSecrets } from './commands/secrets.js';
@@ -895,10 +895,16 @@ db
     return runDb(verb, { file: opts.file, json: opts.json });
 }));
 const features = program.command('features').description('Code-first Ductape Features (ductape/features/)');
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/cli",
-  "version": "0.3.35",
+  "version": "0.3.36",
   "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",