@ductape/cli 0.3.8 → 0.3.10

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)
@@ -20,7 +21,7 @@
 - `ductape workspaces current`, `workspaces switch`, `workspaces refresh`
 - `ductape login --workspace`, `--skip-workspace-select`
 - `ductape link` defaults to active workspace; `whoami` shows `active_workspace`
-- Switching workspaces updates linked `.ductape/config.json` when present
+- Switching workspaces updates linked `ductape/config.json` when present
 
 ## 0.2.0
 

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

@@ -57,5 +57,5 @@ export async function runLink(opts) {
     };
     saveProjectConfig(targetDir, config);
     setActiveWorkspace(workspaceIdValue, workspaceLabel(workspaceSummary), workspaceTagValue);
-    success(`Linked project in ${path.join(targetDir, '.ductape/config.json')}`);
+    success(`Linked project in ${path.join(targetDir, 'ductape/config.json')}`);
 }

package/dist/commands/resources.d.ts

@@ -1,8 +1,20 @@
 import { type CommandInteractiveFlags } from '../lib/interactive-opts.js';
+import type { SDKModule } from '../lib/proxy/sdk-proxy.js';
+export declare function resolveResourceProductTag(override: string | undefined, linkedProductTag: string): string;
+type ResourceProxy = {
+    execute<T>(module: SDKModule, method: string, params?: unknown[]): Promise<T>;
+};
+/**
+ * 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,
+ * so transport, authentication, and genuine server failures are never silently swallowed.
+ */
+export declare function listSessionsWithProductFallback(proxy: ResourceProxy, productTag: string): Promise<unknown[]>;
 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: {
@@ -13,6 +25,8 @@ export declare function runNotificationMessageCrud(verb: string, opts: {
 }): Promise<void>;
 export declare function runResourceCrud(typeName: string, verb: string, opts: {
     tag?: string;
+    product?: string;
     file?: string;
     json?: boolean;
 } & CommandInteractiveFlags, extraArgs: string[]): Promise<void>;
+export {};

package/dist/commands/resources.js

@@ -5,17 +5,84 @@ 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;
+}
+function unwrapArray(value) {
+    if (Array.isArray(value))
+        return value;
+    if (value && typeof value === 'object' && Array.isArray(value.data)) {
+        return value.data;
+    }
+    return undefined;
+}
+/**
+ * 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,
+ * so transport, authentication, and genuine server failures are never silently swallowed.
+ */
+export async function listSessionsWithProductFallback(proxy, productTag) {
+    try {
+        const result = await proxy.execute('sessions', 'list', [productTag]);
+        return unwrapArray(result) ?? [];
+    }
+    catch (listError) {
+        try {
+            const fetched = await proxy.execute('product', 'fetch', [productTag]);
+            const product = fetched && typeof fetched === 'object' && 'data' in fetched
+                ? fetched.data
+                : fetched;
+            if (!product || typeof product !== 'object')
+                throw listError;
+            const sessions = unwrapArray(product.sessions) ?? [];
+            return sessions.filter((session) => !session || typeof session !== 'object' || session.deleted !== true);
+        }
+        catch {
+            throw listError;
+        }
+    }
+}
 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)) {
@@ -23,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,
@@ -32,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')}`);
     }
@@ -57,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 ?? '');
@@ -168,11 +241,28 @@ export async function runResourceCrud(typeName, verb, opts, extraArgs) {
             tag,
         };
     }
-    const params = buildCrudParams(module, method, session.project.product_tag, {
+    const productTag = resolveResourceProductTag(opts.product, session.project.product_tag);
+    const params = buildCrudParams(module, method, productTag, {
         tag,
         body: payload,
     });
     const proxy = getSdkProxy(session);
+    if (crud === 'list' && module === 'sessions') {
+        printJson(await listSessionsWithProductFallback(proxy, productTag), Boolean(opts.json));
+        return;
+    }
     const result = await proxy.execute(module, method, params);
+    if (crud === 'create' && module === 'sessions') {
+        const createdTag = String(body?.tag ?? '').trim();
+        if (!createdTag) {
+            throw new Error('Session creation could not be verified because body.tag is missing');
+        }
+        const verified = await proxy.execute(module, 'fetch', buildCrudParams(module, 'fetch', productTag, { tag: createdTag }));
+        if (!verified) {
+            throw new Error(`Session creation returned without an error, but "${createdTag}" was not found during verification`);
+        }
+        printJson({ created: true, session: verified }, Boolean(opts.json));
+        return;
+    }
     printJson(result, Boolean(opts.json));
 }

package/dist/index.js

@@ -112,7 +112,7 @@ workspaces
     .action(wrap((opts) => runWorkspacesCurrent(Boolean(opts.json))));
 workspaces
     .command('use [selector]')
-    .description('Switch active workspace (interactive picker). Updates linked .ductape/config.json if present')
+    .description('Switch active workspace (interactive picker). Updates linked ductape/config.json if present')
     .option('--profile <name>')
     .option('-C, --dir <path>', 'Project directory to sync', process.cwd())
     .option('--json', 'JSON output')
@@ -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')
@@ -661,6 +662,7 @@ resources
     .argument('<type>', 'Resource type (e.g. storage, database, cache …)')
     .argument('<verb>', 'list | get | create | update | delete | connect')
     .option('-t, --tag <tag>')
+    .option('--product <tag>', 'Product tag (defaults to linked project)')
     .option('-f, --file <path>', 'JSON body (or use interactive prompts)')
     .option('-i, --interactive', 'Prompt for fields (default in TTY when -f omitted)')
     .option('--no-interactive', 'Require -f JSON for create/update/connect')

package/dist/lib/config.js

@@ -9,6 +9,7 @@ export const GLOBAL_CONFIG_PATH = path.join(GLOBAL_DIR, 'config.json');
 export const HUB_PLATFORM_DIR = path.join(GLOBAL_DIR, 'platform');
 export const PROJECT_CONFIG_DIR = 'ductape';
 export const PROJECT_CONFIG_PATH = path.join(PROJECT_CONFIG_DIR, 'config.json');
+const LEGACY_PROJECT_CONFIG_PATH = path.join('.ductape', 'config.json');
 const DEFAULT_GLOBAL = {
     default_profile: 'cloud',
     profiles: {
@@ -114,10 +115,13 @@ export function findProjectConfig(startDir = process.cwd()) {
     let dir = startDir;
     const root = path.parse(dir).root;
     while (true) {
-        const candidate = path.join(dir, PROJECT_CONFIG_PATH);
-        const cfg = readJson(candidate);
-        if (cfg?.product_tag && (cfg.workspace_tag || cfg.workspace_id)) {
-            return { dir, config: cfg };
+        // The CLI writes ductape/config.json. Read the former hidden path only as
+        // an upgrade fallback; canonical config always wins when both exist.
+        for (const relativePath of [PROJECT_CONFIG_PATH, LEGACY_PROJECT_CONFIG_PATH]) {
+            const cfg = readJson(path.join(dir, relativePath));
+            if (cfg?.product_tag && (cfg.workspace_tag || cfg.workspace_id)) {
+                return { dir, config: cfg };
+            }
         }
         if (dir === root)
             break;

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.8",
+  "version": "0.3.10",
   "description": "Ductape CLI — local platform, login, link projects, and manage resources via the proxy (Workbench-compatible)",
   "type": "module",
   "main": "dist/index.js",

package/templates/typescript/ductape.example.ts

@@ -1,6 +1,6 @@
 /**
  * Ductape SDK example — product/env defaults are set on the constructor only.
- * CLI: `ductape login` + `ductape link` (see .ductape/config.json).
+ * CLI: `ductape login` + `ductape link` (see ductape/config.json).
  */
 import Ductape from '@ductape/sdk';