@ductape/cli 0.3.9 → 0.3.11

package/CHANGELOG.md

@@ -11,6 +11,7 @@
 
 ### Added
 
+- Canonical one-topic-per-file Events validation, `events topics validate`, preflighted `create-all`, publisher-reference checks, and an init-generated `ductape/validate-events.sh` CI script.
 - `ductape apps import <file> --type postman|openapi` (Postman v2.1 / OpenAPI 3.0)
 - Project config uses `workspace_tag` (CLI resolves `workspace_id` automatically)
 - `ductape products` and `ductape apps` CRUD (workspace REST + sdk-proxy update)

package/README.md

@@ -72,6 +72,8 @@ ductape apps list|get|create|update|delete|import
 ductape init|link|unlink
 ductape start|stop|status   # status explains proxy 502 when backend is down
 ductape resources <type> <verb>   # CRUD via sdk-proxy (interactive prompts or -f JSON)
+ductape events topics validate --dir ductape/events
+ductape events topics create-all --dir ductape/events
 ductape cloud connections list|create|get|update|complete|validate|delete
 ductape cloud resources list|import|provision …
 ductape db <verb>                 # db-proxy runtime
@@ -83,6 +85,16 @@ ductape generate payload|snippet …
 ductape completion bash|zsh
 ```
 
+## Event topic assets
+
+Ductape topic assets are individual, directly importable files at
+`ductape/events/<topic-tag>.topic.json`. Each file contains exactly one topic object whose fully
+qualified `tag` is `broker-tag:topic-tag`; the filename uses the unqualified topic portion.
+Aggregate catalogues, manifests, envelope registries, and custom event registries are rejected.
+
+Run `ductape events topics validate --dir ductape/events --json` in CI. `create-all` validates every
+file and publisher reference before performing its first remote mutation.
+
 ## Documentation
 
 Full reference: [docs/docs/cli/](../docs/docs/cli/index.mdx)

package/dist/commands/graph.d.ts

@@ -1,3 +1,7 @@
+export declare function validateGraphActionFile(file: string | undefined, body: Record<string, unknown>): {
+    graphTag: string;
+    actionTag: string;
+};
 export declare function runGraph(method: string, opts: {
     file?: string;
     json?: boolean;

package/dist/commands/graph.js

@@ -3,16 +3,80 @@ import { setGraphContext } from '../lib/context-store.js';
 import { GRAPH_PROXY_METHODS } from '../lib/db-methods.js';
 import { getGraphProxy, requireSession } from '../lib/proxy/context.js';
 import { printJson } from '../lib/output.js';
+import path from 'node:path';
+const GRAPH_ACTION_FIELDS = new Set(['graphTag', 'name', 'description', 'operation', 'query', 'parameters']);
+function actionSlug(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+export function validateGraphActionFile(file, body) {
+    if (!file)
+        throw new Error('Graph action validation requires -f ductape/graphs/<graph-tag>/actions/<action-tag>.action.json');
+    for (const field of ['graphTag', 'name', 'operation', 'query', 'parameters']) {
+        if (!(field in body))
+            throw new Error(`Graph action is missing required field "${field}"`);
+    }
+    for (const field of Object.keys(body)) {
+        if (!GRAPH_ACTION_FIELDS.has(field))
+            throw new Error(`Unknown graph action field "${field}"`);
+    }
+    if (typeof body.graphTag !== 'string' || !body.graphTag)
+        throw new Error('graphTag must be a non-empty string');
+    if (typeof body.name !== 'string' || !body.name)
+        throw new Error('name must be a non-empty string');
+    if (typeof body.operation !== 'string' || !body.operation)
+        throw new Error('operation must be a non-empty string');
+    if (!body.query || typeof body.query !== 'object' || Array.isArray(body.query))
+        throw new Error('query must be an object');
+    if (!Array.isArray(body.parameters))
+        throw new Error('parameters must be an array');
+    for (const [index, parameter] of body.parameters.entries()) {
+        if (!parameter || typeof parameter !== 'object' || Array.isArray(parameter))
+            throw new Error(`parameters[${index}] must be an object`);
+        const value = parameter;
+        for (const field of ['name', 'path', 'defaultValue', 'type']) {
+            if (!(field in value))
+                throw new Error(`parameters[${index}] is missing required field "${field}"`);
+        }
+        if (!['string', 'number', 'boolean', 'array', 'object'].includes(String(value.type))) {
+            throw new Error(`parameters[${index}].type is invalid`);
+        }
+    }
+    const actionTag = actionSlug(body.name);
+    const normalized = file.replaceAll('\\', '/');
+    const expectedSuffix = `ductape/graphs/${body.graphTag}/actions/${actionTag}.action.json`;
+    if (!normalized.endsWith(expectedSuffix))
+        throw new Error(`Graph action must be stored at ${expectedSuffix}`);
+    if (path.basename(file) !== `${actionTag}.action.json`)
+        throw new Error(`Graph action filename must be ${actionTag}.action.json`);
+    return { graphTag: body.graphTag, actionTag };
+}
 export async function runGraph(method, opts) {
     const session = requireSession();
     const proxy = getGraphProxy(session);
     const body = readJsonBody(opts.file);
     const m = method.includes('.') ? method : method.toLowerCase();
+    if (m === 'validateaction') {
+        const validated = validateGraphActionFile(opts.file, body);
+        printJson({ valid: true, file: opts.file, ...validated }, Boolean(opts.json));
+        return;
+    }
     if (!GRAPH_PROXY_METHODS.includes(m) && !m.includes('.')) {
         console.warn(`Method "${m}" not in known list; sending anyway. Known: ${GRAPH_PROXY_METHODS.join(', ')}`);
     }
     const params = [];
-    if (m === 'connect') {
+    if (m === 'createaction') {
+        validateGraphActionFile(opts.file, body);
+        params.push(body, session.project.product_tag);
+    }
+    else if (m === 'updateaction') {
+        const actionTag = String(body.actionTag ?? '');
+        const graphTag = String(body.graphTag ?? '');
+        if (!actionTag || !graphTag || !body.updates || typeof body.updates !== 'object') {
+            throw new Error('updateAction requires { "actionTag", "graphTag", "updates": { ... } }');
+        }
+        params.push(actionTag, body.updates, graphTag, session.project.product_tag);
+    }
+    else if (m === 'connect') {
         const cfg = {
             product: session.project.product_tag,
             env: session.project.env_slug,

package/dist/commands/resources.d.ts

@@ -14,6 +14,7 @@ export declare function runResourcesList(json: boolean): void;
 export declare function runEventTopicCrud(verb: string, opts: {
     tag?: string;
     file?: string;
+    dir?: string;
     json?: boolean;
 } & CommandInteractiveFlags, extraArgs: string[]): Promise<void>;
 export declare function runNotificationMessageCrud(verb: string, opts: {

package/dist/commands/resources.js

@@ -5,6 +5,7 @@ import { toInteractiveOpts } from '../lib/interactive-opts.js';
 import { bodyRequiredHint, resolveBody } from '../lib/read-body.js';
 import { requireSession, getSdkProxy } from '../lib/proxy/context.js';
 import { printJson } from '../lib/output.js';
+import { readCanonicalTopicFile, topicBodyForTransport, validateEventTopicsProject, } from '../lib/event-topics.js';
 const CRUD_VERBS = ['create', 'list', 'get', 'update', 'delete', 'connect'];
 export function resolveResourceProductTag(override, linkedProductTag) {
     return override?.trim() || linkedProductTag;
@@ -47,12 +48,41 @@ export function runResourcesList(json) {
     printJson({ resource_types: listResourceTypes() }, json);
 }
 export async function runEventTopicCrud(verb, opts, extraArgs) {
+    if (verb === 'validate') {
+        const validation = await validateEventTopicsProject(process.cwd(), opts.dir);
+        printJson({
+            valid: true,
+            directory: validation.directory,
+            topics: validation.topics.map(({ file, definition }) => ({ file, tag: definition.tag })),
+            publisher_topics: validation.publisherTopics,
+        }, Boolean(opts.json));
+        return;
+    }
     const crud = verb.toLowerCase();
-    if (!CRUD_VERBS.includes(crud)) {
-        throw new Error(`Unknown verb "${verb}". Use: ${CRUD_VERBS.join(', ')}`);
+    if (!CRUD_VERBS.includes(crud) && verb !== 'create-all') {
+        throw new Error(`Unknown verb "${verb}". Use: ${[...CRUD_VERBS, 'validate', 'create-all'].join(', ')}`);
     }
     const session = requireSession();
     const productTag = session.project.product_tag;
+    const proxy = getSdkProxy(session);
+    if (verb === 'create-all') {
+        const validation = await validateEventTopicsProject(process.cwd(), opts.dir);
+        const created = [];
+        // Validation of the complete directory deliberately finishes before the first mutation.
+        for (const topic of validation.topics) {
+            await proxy.execute('messageBrokers', 'topics.create', [
+                productTag,
+                topicBodyForTransport(topic.definition),
+            ]);
+            const verified = await proxy.execute('messageBrokers', 'topics.fetch', [productTag, topic.definition.tag]);
+            if (!verified) {
+                throw new Error(`Topic creation returned without an error, but "${topic.definition.tag}" was not found during verification`);
+            }
+            created.push({ tag: topic.definition.tag, topic: verified });
+        }
+        printJson({ created: created.length, topics: created }, Boolean(opts.json));
+        return;
+    }
     const interactive = toInteractiveOpts(opts);
     let tag = opts.tag ?? extraArgs[0];
     if (!tag && ['get', 'update', 'delete', 'list'].includes(crud) && isInteractive(interactive)) {
@@ -60,7 +90,7 @@ export async function runEventTopicCrud(verb, opts, extraArgs) {
     }
     const method = crud === 'get' ? 'topics.fetch' : `topics.${crud}`;
     const needsBody = crud === 'create' || crud === 'update';
-    const body = needsBody
+    let body = needsBody
         ? await resolveBody({
             ...interactive,
             file: opts.file,
@@ -69,6 +99,13 @@ export async function runEventTopicCrud(verb, opts, extraArgs) {
             requireBody: crud === 'create',
         })
         : undefined;
+    if (crud === 'create') {
+        if (!opts.file) {
+            throw new Error('Topic creation requires -f ductape/events/<topic-tag>.topic.json');
+        }
+        const canonical = await readCanonicalTopicFile(opts.file, process.cwd());
+        body = topicBodyForTransport(canonical.definition);
+    }
     if (crud === 'create' && (!body || Object.keys(body).length === 0)) {
         throw new Error(`create requires a body. ${bodyRequiredHint('messageBrokers:topics:create')}`);
     }
@@ -94,7 +131,6 @@ export async function runEventTopicCrud(verb, opts, extraArgs) {
     else {
         throw new Error(`Unsupported verb "${crud}" for events topics`);
     }
-    const proxy = getSdkProxy(session);
     const result = await proxy.execute('messageBrokers', method, params);
     if (crud === 'create') {
         const fullTag = String(body?.tag ?? '');

package/dist/index.js

@@ -640,9 +640,10 @@ program
 const events = program.command('events').description('Message broker CRUD (sdk-proxy, requires access key login)');
 const eventTopics = events.command('topics').description('Topic CRUD for a message broker');
 eventTopics
-    .argument('<verb>', 'list | get | create | update | delete')
+    .argument('<verb>', 'list | get | create | update | delete | validate | create-all')
     .option('-t, --tag <tag>', 'Broker tag (list) or topic tag in broker:topic form (get, update, delete)')
     .option('-f, --file <path>', 'JSON body (create, update)')
+    .option('--dir <path>', 'Events asset directory (must resolve to ductape/events)', 'ductape/events')
     .option('-i, --interactive', 'Prompt for fields (default in TTY when -f omitted)')
     .option('--no-interactive', 'Require -f JSON for create/update')
     .option('--json', 'JSON output')
@@ -734,7 +735,7 @@ db
 }));
 const graph = program.command('graph').description('Graph runtime (graph-proxy)');
 graph
-    .argument('<verb>', 'connect | query | …')
+    .argument('<verb>', 'connect | query | createAction | validateAction | updateAction | …')
     .option('-f, --file <path>')
     .option('--json', 'JSON output')
     .action(wrap((verb, opts) => runGraph(verb, { file: opts.file, json: opts.json })));

package/dist/lib/event-topics.d.ts

@@ -0,0 +1,29 @@
+export interface EventTopicDefinition {
+    tag: string;
+    name: string;
+    description?: string;
+    sample?: Record<string, unknown>;
+    idempotent?: boolean;
+    queueUrls?: Array<{
+        env_slug: string;
+        url: string;
+    }>;
+}
+export interface ValidatedEventTopic {
+    file: string;
+    definition: EventTopicDefinition;
+}
+export interface EventTopicProjectValidation {
+    valid: true;
+    directory: string;
+    topics: ValidatedEventTopic[];
+    publisherTopics: string[];
+}
+export declare function expectedTopicFilename(tag: string): string;
+export declare function validateEventTopicDefinition(value: unknown, file?: string): EventTopicDefinition;
+export declare function canonicalEventsDirectory(projectRoot?: string): string;
+export declare function assertCanonicalTopicFile(file: string, definition: EventTopicDefinition, projectRoot?: string): void;
+export declare function readCanonicalTopicFile(file: string, projectRoot?: string): Promise<ValidatedEventTopic>;
+export declare function findPublishedTopicTags(projectRoot?: string): Promise<string[]>;
+export declare function validateEventTopicsProject(projectRoot?: string, requestedDirectory?: string): Promise<EventTopicProjectValidation>;
+export declare function topicBodyForTransport(definition: EventTopicDefinition): Record<string, unknown>;

package/dist/lib/event-topics.js

@@ -0,0 +1,155 @@
+import { promises as fs } from 'node:fs';
+import { basename, relative, resolve, sep } from 'node:path';
+const TOPIC_KEYS = new Set(['tag', 'name', 'description', 'sample', 'idempotent', 'queueUrls']);
+const IGNORED_DIRECTORY_ENTRIES = new Set(['README.md', '.gitkeep', '.DS_Store']);
+const SKIPPED_SCAN_DIRECTORIES = new Set([
+    '.git', 'node_modules', 'dist', 'build', 'coverage', '.next', '.nuxt', 'vendor', 'target', 'bin', 'obj',
+]);
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.go', '.java', '.cs', '.py']);
+const TAG_SEGMENT = '[A-Za-z0-9]+(?:[-_][A-Za-z0-9]+)*';
+const FULLY_QUALIFIED_TAG = new RegExp(`^${TAG_SEGMENT}:${TAG_SEGMENT}$`);
+const SQS_QUEUE_URL = /^https:\/\/sqs\.[a-z0-9-]+\.amazonaws\.com\/\d{12}\/[a-zA-Z0-9_-]{1,80}(\.fifo)?$/;
+function assertObject(value, file) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${file}: a topic file must contain exactly one JSON object (arrays and aggregate catalogues are forbidden)`);
+    }
+}
+export function expectedTopicFilename(tag) {
+    if (!FULLY_QUALIFIED_TAG.test(tag)) {
+        throw new Error(`Topic tag "${tag}" must be fully qualified as broker-tag:topic-tag`);
+    }
+    return `${tag.slice(tag.indexOf(':') + 1)}.topic.json`;
+}
+export function validateEventTopicDefinition(value, file = 'topic definition') {
+    assertObject(value, file);
+    const unknown = Object.keys(value).filter((key) => !TOPIC_KEYS.has(key));
+    if (unknown.length)
+        throw new Error(`${file}: unknown topic field(s): ${unknown.join(', ')}`);
+    if (typeof value.tag !== 'string' || !FULLY_QUALIFIED_TAG.test(value.tag)) {
+        throw new Error(`${file}: tag is required and must be fully qualified as broker-tag:topic-tag`);
+    }
+    if (typeof value.name !== 'string' || !value.name.trim()) {
+        throw new Error(`${file}: name is required and must be a non-empty string`);
+    }
+    if (value.description !== undefined && (typeof value.description !== 'string' || !value.description.trim())) {
+        throw new Error(`${file}: description must be a non-empty string when supplied`);
+    }
+    if (value.sample !== undefined && (!value.sample || typeof value.sample !== 'object' || Array.isArray(value.sample))) {
+        throw new Error(`${file}: sample must be a JSON object`);
+    }
+    if (value.idempotent !== undefined && typeof value.idempotent !== 'boolean') {
+        throw new Error(`${file}: idempotent must be a boolean`);
+    }
+    if (value.queueUrls !== undefined) {
+        if (!Array.isArray(value.queueUrls) || value.queueUrls.some((entry) => !entry || typeof entry !== 'object' || Array.isArray(entry) ||
+            Object.keys(entry).some((key) => key !== 'env_slug' && key !== 'url') ||
+            typeof entry.env_slug !== 'string' ||
+            !entry.env_slug ||
+            typeof entry.url !== 'string' ||
+            !SQS_QUEUE_URL.test(entry.url))) {
+            throw new Error(`${file}: queueUrls must contain only { env_slug, url } objects with valid AWS SQS queue URLs`);
+        }
+    }
+    return value;
+}
+export function canonicalEventsDirectory(projectRoot = process.cwd()) {
+    return resolve(projectRoot, 'ductape', 'events');
+}
+export function assertCanonicalTopicFile(file, definition, projectRoot = process.cwd()) {
+    const absoluteFile = resolve(projectRoot, file);
+    const eventsDirectory = canonicalEventsDirectory(projectRoot);
+    const rel = relative(eventsDirectory, absoluteFile);
+    if (!rel || rel.startsWith(`..${sep}`) || rel === '..' || rel.includes(sep)) {
+        throw new Error(`${file}: topic assets must be direct files under ${eventsDirectory}`);
+    }
+    const expected = expectedTopicFilename(definition.tag);
+    if (basename(absoluteFile) !== expected) {
+        throw new Error(`${file}: filename must be "${expected}" for topic tag "${definition.tag}"`);
+    }
+}
+export async function readCanonicalTopicFile(file, projectRoot = process.cwd()) {
+    const absoluteFile = resolve(projectRoot, file);
+    let parsed;
+    try {
+        parsed = JSON.parse(await fs.readFile(absoluteFile, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`${file}: could not read valid JSON (${error instanceof Error ? error.message : String(error)})`);
+    }
+    const definition = validateEventTopicDefinition(parsed, file);
+    assertCanonicalTopicFile(absoluteFile, definition, projectRoot);
+    return { file: absoluteFile, definition };
+}
+async function walkSourceFiles(directory, output) {
+    let entries;
+    try {
+        entries = await fs.readdir(directory, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory() && SKIPPED_SCAN_DIRECTORIES.has(entry.name))
+            continue;
+        const path = resolve(directory, entry.name);
+        if (entry.isDirectory())
+            await walkSourceFiles(path, output);
+        else if (entry.isFile() && SOURCE_EXTENSIONS.has(entry.name.slice(entry.name.lastIndexOf('.'))))
+            output.push(path);
+    }
+}
+export async function findPublishedTopicTags(projectRoot = process.cwd()) {
+    const files = [];
+    await walkSourceFiles(resolve(projectRoot), files);
+    const tags = new Set();
+    const patterns = [
+        /\.(?:publish|produce|dispatch)\s*\(\s*\{[^)]{0,2000}?\b(?:event|topic)\s*:\s*['"`]([A-Za-z0-9._-]+:[A-Za-z0-9._-]+)['"`]/gs,
+        /\.(?:publish|produce|dispatch)\s*\(\s*['"`]([A-Za-z0-9._-]+:[A-Za-z0-9._-]+)['"`]/g,
+    ];
+    for (const file of files) {
+        const source = await fs.readFile(file, 'utf8');
+        for (const pattern of patterns) {
+            pattern.lastIndex = 0;
+            for (let match = pattern.exec(source); match; match = pattern.exec(source))
+                tags.add(match[1]);
+        }
+    }
+    return [...tags].sort();
+}
+export async function validateEventTopicsProject(projectRoot = process.cwd(), requestedDirectory) {
+    const directory = canonicalEventsDirectory(projectRoot);
+    if (requestedDirectory && resolve(projectRoot, requestedDirectory) !== directory) {
+        throw new Error(`Events directory must be ${directory}; custom topic directories are not supported`);
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(directory, { withFileTypes: true });
+    }
+    catch {
+        throw new Error(`Missing required events directory: ${directory}`);
+    }
+    const unexpected = entries
+        .filter((entry) => !entry.isFile() || (!entry.name.endsWith('.topic.json') && !IGNORED_DIRECTORY_ENTRIES.has(entry.name)))
+        .map((entry) => entry.name);
+    if (unexpected.length) {
+        throw new Error(`${directory}: unsupported entries: ${unexpected.join(', ')}. Only one-topic-per-file *.topic.json assets are allowed`);
+    }
+    const files = entries.filter((entry) => entry.isFile() && entry.name.endsWith('.topic.json'));
+    const topics = await Promise.all(files.map((entry) => readCanonicalTopicFile(resolve(directory, entry.name), projectRoot)));
+    const seen = new Set();
+    for (const topic of topics) {
+        if (seen.has(topic.definition.tag))
+            throw new Error(`Duplicate topic tag: ${topic.definition.tag}`);
+        seen.add(topic.definition.tag);
+    }
+    const publisherTopics = await findPublishedTopicTags(projectRoot);
+    const undefinedTopics = publisherTopics.filter((tag) => !seen.has(tag));
+    if (undefinedTopics.length) {
+        throw new Error(`Application publishers reference undefined topic(s): ${undefinedTopics.join(', ')}`);
+    }
+    return { valid: true, directory, topics, publisherTopics };
+}
+export function topicBodyForTransport(definition) {
+    // SDK releases through 0.1.120 require sample even though it is optional in the asset contract.
+    return { ...definition, sample: definition.sample ?? {} };
+}

package/dist/lib/templates.js

@@ -137,6 +137,31 @@ Docs: https://docs.ductape.app/docs/cli/
         ];
         fs.writeFileSync(eventsPath, JSON.stringify(eventsTemplate, null, 2) + '\n');
     }
+    const topicAssetsDir = path.join(ductapeDir, 'events');
+    fs.mkdirSync(topicAssetsDir, { recursive: true });
+    const topicReadmePath = path.join(topicAssetsDir, 'README.md');
+    if (!fs.existsSync(topicReadmePath)) {
+        fs.writeFileSync(topicReadmePath, `# Ductape Event topics
+
+Store exactly one directly importable topic object per file:
+
+\`ductape/events/<topic-tag>.topic.json\`
+
+The JSON \`tag\` must be fully qualified as \`broker-tag:topic-tag\`, while the filename uses
+the unqualified topic portion. Aggregate catalogues, manifests, and envelope registries are invalid.
+
+Validate locally and in CI:
+
+\`\`\`bash
+ductape events topics validate --dir ductape/events --json
+\`\`\`
+`);
+    }
+    const validationScriptPath = path.join(ductapeDir, 'validate-events.sh');
+    if (!fs.existsSync(validationScriptPath)) {
+        fs.writeFileSync(validationScriptPath, '#!/usr/bin/env sh\nset -eu\nductape events topics validate --dir ductape/events --json\n');
+        fs.chmodSync(validationScriptPath, 0o755);
+    }
     copyTemplate(lang, dir);
     const gitignorePath = path.join(dir, '.gitignore');
     if (fs.existsSync(gitignorePath)) {

package/package.json

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