cognitive-modules-cli 2.2.5 → 2.2.8

package/CHANGELOG.md

@@ -2,7 +2,13 @@
 
 All notable changes to this package are documented in this file.
 
-## 2.2.5 - 2026-02-06
+## 2.2.8 - 2026-02-07
+
+- Fix: `npx cogn` alias compatibility on newer Node (exports + ESM). (Alias fix ships in `cogn@2.2.8`.)
+- Hardening: configurable registry index fetch limits (`--registry-timeout-ms`, `--registry-max-bytes`).
+- Hardening: remote registry verification supports bounded concurrency (`--concurrency`).
+
+## 2.2.7 - 2026-02-06
 
 - Standardized v2.2 runtime behavior and cross-surface error envelope consistency (CLI/HTTP/MCP).
 - Clarified `compose` output contract: default/pretty output returns full v2.2 envelope, while `compose --trace` returns a debug wrapper object (`result/moduleResults/trace/totalTimeMs`) for diagnostics.

package/README.md

@@ -10,12 +10,12 @@ Node.js/TypeScript 版本的 Cognitive Modules CLI，提供 `cog` 命令。
 
 ```bash
 # 全局安装（推荐）
-npm install -g cogn@2.2.5
+npm install -g cogn@2.2.8
 # 或使用完整包名（同样提供 `cog` 命令）
-# npm install -g cognitive-modules-cli@2.2.5
+# npm install -g cognitive-modules-cli@2.2.8
 
 # 或使用 npx 零安装
-npx cogn@2.2.5 --help
+npx cogn@2.2.8 --help
 ```
 
 ## 快速开始
@@ -50,6 +50,18 @@ echo "review this code" | cog pipe --module code-reviewer
 ## 命令
 
 ```bash
+# Core（单文件极简路径）
+cog core new                       # 生成 demo.md
+cog core run demo.md --args "..."  # 运行单文件模块
+cog core promote demo.md           # 升级为 v2 模块目录
+
+# 渐进复杂度（Profiles）
+cog run code-reviewer --args "..." --profile core       # 极简：跳过校验
+cog run code-reviewer --args "..." --profile default    # 默认：开启校验
+cog run code-reviewer --args "..." --profile strict     # 更严格：开启校验（更强门禁）
+cog run code-reviewer --args "..." --profile certified  # 最严格：v2.2 + 审计 + registry provenance/完整性门禁
+# 覆盖开关：--validate auto|on|off，--audit（写入 ~/.cognitive/audit/）
+
 # 模块操作
 cog list                      # 列出模块
 cog run <module> --args "..." # 运行模块
@@ -76,6 +88,16 @@ cog mcp                       # 启动 MCP 服务（Claude Code / Cursor）
 
 # 环境检查
 cog doctor
+
+# Registry（索引与分发）
+# 默认 registry index（latest）：
+#   https://github.com/Cognary/cognitive/releases/latest/download/cognitive-registry.v2.json
+# 可通过环境变量或全局参数覆盖：
+COGNITIVE_REGISTRY_URL=... cog search
+COGNITIVE_REGISTRY_TIMEOUT_MS=15000 COGNITIVE_REGISTRY_MAX_BYTES=2097152 cog search
+cog search --registry https://github.com/Cognary/cognitive/releases/download/v2.2.8/cognitive-registry.v2.json
+cog registry verify --remote --index https://github.com/Cognary/cognitive/releases/latest/download/cognitive-registry.v2.json
+cog registry verify --remote --concurrency 2
 ```
 
 ## 开发

package/dist/audit.d.ts

@@ -0,0 +1,13 @@
+export interface AuditRecord {
+    ts: string;
+    kind: 'run' | 'pipe' | 'compose';
+    policy?: unknown;
+    provider?: string;
+    module?: unknown;
+    input?: unknown;
+    result?: unknown;
+    notes?: string[];
+}
+export declare function writeAuditRecord(record: AuditRecord): Promise<{
+    path: string;
+} | null>;

package/dist/audit.js

@@ -0,0 +1,25 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+function safeSlug(s) {
+    const out = s.trim().toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9._-]/g, '-');
+    return out.length > 0 ? out.slice(0, 80) : 'unknown';
+}
+export async function writeAuditRecord(record) {
+    // Keep it simple and predictable: write under ~/.cognitive/audit/
+    const dir = path.join(os.homedir(), '.cognitive', 'audit');
+    const ts = record.ts.replace(/[:.]/g, '-');
+    const kind = record.kind;
+    const moduleName = safeSlug(typeof record.module?.name === 'string' ? record.module.name : 'module');
+    const filename = `${ts}-${kind}-${moduleName}-${Math.random().toString(16).slice(2, 10)}.json`;
+    try {
+        await fs.mkdir(dir, { recursive: true });
+        const outPath = path.join(dir, filename);
+        await fs.writeFile(outPath, JSON.stringify(record, null, 2) + '\n', 'utf-8');
+        return { path: outPath };
+    }
+    catch {
+        // Audit must never break execution.
+        return null;
+    }
+}

package/dist/cli.js

@@ -15,9 +15,12 @@
  */
 import { parseArgs } from 'node:util';
 import { getProvider, listProviders } from './providers/index.js';
-import { run, list, pipe, init, add, update, remove, versions, compose, composeInfo, validate, validateAll, migrate, migrateAll, test, testAll, search, listCategories, info } from './commands/index.js';
+import { run, list, pipe, init, add, update, remove, versions, compose, composeInfo, validate, validateAll, migrate, migrateAll, test, testAll, search, listCategories, info, core } from './commands/index.js';
 import { listModules, getDefaultSearchPaths } from './modules/loader.js';
 import { VERSION } from './version.js';
+import { resolveExecutionPolicy } from './profile.js';
+import { buildRegistryAssets, verifyRegistryAssets } from './registry/assets.js';
+import { DEFAULT_REGISTRY_URL } from './registry/client.js';
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
@@ -33,6 +36,12 @@ async function main() {
     const { values, positionals } = parseArgs({
         args: args.slice(1),
         options: {
+            help: { type: 'boolean', short: 'h', default: false },
+            stdin: { type: 'boolean', default: false }, // core: read module prompt from stdin
+            force: { type: 'boolean', default: false }, // core promote: overwrite existing target dir
+            profile: { type: 'string' }, // progressive complexity profile
+            validate: { type: 'string' }, // auto|on|off (overrides --no-validate)
+            audit: { type: 'boolean', default: false }, // write audit record to ~/.cognitive/audit/
             args: { type: 'string', short: 'a' },
             input: { type: 'string', short: 'i' },
             module: { type: 'string', short: 'm' },
@@ -41,6 +50,7 @@ async function main() {
             pretty: { type: 'boolean', default: false },
             verbose: { type: 'boolean', short: 'V', default: false },
             'no-validate': { type: 'boolean', default: false },
+            stream: { type: 'boolean', default: false },
             // Add/update options
             name: { type: 'string', short: 'n' },
             tag: { type: 'string', short: 't' },
@@ -61,9 +71,59 @@ async function main() {
             format: { type: 'string', short: 'f' },
             // Search options
             category: { type: 'string', short: 'c' },
+            registry: { type: 'string' }, // override registry index URL (or use env COGNITIVE_REGISTRY_URL)
+            'registry-timeout-ms': { type: 'string' },
+            'registry-max-bytes': { type: 'string' },
+            // Registry build/verify options
+            'modules-dir': { type: 'string' },
+            'v1-registry': { type: 'string' },
+            'out-dir': { type: 'string' },
+            'registry-out': { type: 'string' },
+            namespace: { type: 'string' },
+            'runtime-min': { type: 'string' },
+            repository: { type: 'string' },
+            homepage: { type: 'string' },
+            license: { type: 'string' },
+            timestamp: { type: 'string' },
+            only: { type: 'string', multiple: true },
+            index: { type: 'string' },
+            'assets-dir': { type: 'string' },
+            'tarball-base-url': { type: 'string' },
+            remote: { type: 'boolean', default: false }, // registry verify: fetch index + tarballs over network
+            'fetch-timeout-ms': { type: 'string' },
+            'max-index-bytes': { type: 'string' },
+            'max-tarball-bytes': { type: 'string' },
+            concurrency: { type: 'string' },
         },
         allowPositionals: true,
     });
+    if (values.help) {
+        if (command === 'core') {
+            console.log(JSON.stringify({
+                usage: [
+                    'cog core new [file.md] [--dry-run]',
+                    'cog core schema <file.md> [--pretty]',
+                    'cog core run <file.md> [--args \"...\"] [--pretty] [--stream] [--no-validate]',
+                    'cog core run --stdin [--args \"...\"] [--pretty] [--stream] [--no-validate]',
+                    'cog core promote <file.md> [outDir] [--dry-run] [--force]',
+                ],
+            }, null, values.pretty ? 2 : 0));
+            process.exit(0);
+        }
+        printHelp();
+        process.exit(0);
+    }
+    // Guard Core-only flags so we don't silently ignore them on other commands.
+    if (command !== 'core') {
+        if (values.stdin) {
+            console.error('Error: --stdin is only supported for `cog core run --stdin`');
+            process.exit(1);
+        }
+        if (values.force) {
+            console.error('Error: --force is only supported for `cog core promote --force`');
+            process.exit(1);
+        }
+    }
     // Get provider
     let provider;
     try {
@@ -73,13 +133,64 @@ async function main() {
         console.error(`Error: ${e instanceof Error ? e.message : e}`);
         process.exit(1);
     }
+    let policy;
+    try {
+        policy = resolveExecutionPolicy({
+            profile: values.profile,
+            validate: values.validate,
+            noValidate: values['no-validate'],
+            audit: values.audit,
+        });
+    }
+    catch (e) {
+        console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+    }
+    const parsePositive = (key, raw) => {
+        if (raw === undefined || raw === null || raw === '')
+            return undefined;
+        const n = Number(raw);
+        if (!Number.isFinite(n) || n <= 0) {
+            throw new Error(`Invalid --${key}: ${String(raw)} (expected a positive number)`);
+        }
+        return Math.floor(n);
+    };
     const ctx = {
         cwd: process.cwd(),
         provider,
         verbose: values.verbose,
+        policy,
+        registryUrl: values.registry ?? undefined,
+        registryTimeoutMs: parsePositive('registry-timeout-ms', values['registry-timeout-ms']),
+        registryMaxBytes: parsePositive('registry-max-bytes', values['registry-max-bytes']),
     };
     try {
         switch (command) {
+            case 'core': {
+                const sub = positionals[0];
+                const target = positionals[1];
+                const rest = positionals.slice(2);
+                const result = await core(sub, target, ctx, {
+                    args: values.args,
+                    input: values.input,
+                    noValidate: values['no-validate'],
+                    pretty: values.pretty,
+                    verbose: values.verbose,
+                    stream: values.stream,
+                    dryRun: values['dry-run'],
+                    stdin: values.stdin,
+                    force: values.force,
+                }, rest);
+                if (!result.success) {
+                    console.error(`Error: ${result.error}`);
+                    process.exit(1);
+                }
+                // Stream mode prints events as NDJSON already (via `cog run`).
+                if (!(values.stream && sub === 'run')) {
+                    console.log(JSON.stringify(result.data, null, values.pretty ? 2 : 0));
+                }
+                break;
+            }
             case 'run': {
                 const moduleName = args[1];
                 if (!moduleName || moduleName.startsWith('-')) {
@@ -89,9 +200,11 @@ async function main() {
                 const result = await run(moduleName, ctx, {
                     args: values.args,
                     input: values.input,
+                    // policy.validate is resolved in run(); keep legacy flag compatibility here.
                     noValidate: values['no-validate'],
                     pretty: values.pretty,
                     verbose: values.verbose,
+                    stream: values.stream,
                 });
                 if (!result.success) {
                     if (result.data) {
@@ -102,7 +215,10 @@ async function main() {
                     }
                     process.exit(1);
                 }
-                console.log(JSON.stringify(result.data, null, values.pretty ? 2 : 0));
+                // Stream mode prints events as NDJSON already.
+                if (!values.stream) {
+                    console.log(JSON.stringify(result.data, null, values.pretty ? 2 : 0));
+                }
                 break;
             }
             case 'list': {
@@ -383,6 +499,7 @@ async function main() {
                 const result = await compose(moduleName, ctx, {
                     args: values.args,
                     input: values.input,
+                    noValidate: values['no-validate'],
                     maxDepth: values['max-depth'] ? parseInt(values['max-depth'], 10) : undefined,
                     timeout: values.timeout ? parseInt(values.timeout, 10) : undefined,
                     trace: values.trace,
@@ -765,6 +882,52 @@ async function main() {
                     await client.fetchRegistry(true);
                     console.log('✓ Registry cache refreshed');
                 }
+                else if (subCommand === 'build') {
+                    const result = await buildRegistryAssets({
+                        tag: values.tag ?? null,
+                        tarballBaseUrl: values['tarball-base-url'] ?? null,
+                        modulesDir: values['modules-dir'] ?? 'cognitive/modules',
+                        v1RegistryPath: values['v1-registry'] ?? 'cognitive-registry.json',
+                        outDir: values['out-dir'] ?? 'dist/registry-assets',
+                        registryOut: values['registry-out'] ?? 'cognitive-registry.v2.json',
+                        namespace: values.namespace ?? 'official',
+                        runtimeMin: values['runtime-min'] ?? '2.2.0',
+                        repository: values.repository ?? 'https://github.com/Cognary/cognitive',
+                        homepage: values.homepage ?? 'https://cognary.github.io/cognitive/',
+                        license: values.license ?? 'MIT',
+                        timestamp: values.timestamp ?? null,
+                        only: Array.isArray(values.only) ? values.only : (values.only ? [String(values.only)] : []),
+                    });
+                    console.log(JSON.stringify({ ok: true, ...result }, null, values.pretty ? 2 : 0));
+                }
+                else if (subCommand === 'verify') {
+                    const remote = Boolean(values.remote);
+                    const defaultIndex = (typeof process.env.COGNITIVE_REGISTRY_URL === 'string' && process.env.COGNITIVE_REGISTRY_URL.trim()
+                        ? process.env.COGNITIVE_REGISTRY_URL.trim()
+                        : undefined) ??
+                        ctx.registryUrl ??
+                        DEFAULT_REGISTRY_URL;
+                    const indexPath = values.index ??
+                        (remote ? defaultIndex : 'cognitive-registry.v2.json');
+                    const assetsDir = values['assets-dir'] ?? (remote ? undefined : 'dist/registry-assets');
+                    const fetchTimeoutMs = parsePositive('fetch-timeout-ms', values['fetch-timeout-ms']);
+                    const maxIndexBytes = parsePositive('max-index-bytes', values['max-index-bytes']);
+                    const maxTarballBytes = parsePositive('max-tarball-bytes', values['max-tarball-bytes']);
+                    const concurrency = parsePositive('concurrency', values.concurrency);
+                    const verified = await verifyRegistryAssets({
+                        registryIndexPath: indexPath,
+                        assetsDir,
+                        remote,
+                        fetchTimeoutMs,
+                        maxIndexBytes,
+                        maxTarballBytes,
+                        concurrency,
+                    });
+                    console.log(JSON.stringify(verified, null, values.pretty ? 2 : 0));
+                    if (!verified.ok) {
+                        process.exit(1);
+                    }
+                }
                 else {
                     console.error(`Unknown registry subcommand: ${subCommand}`);
                     console.error('');
@@ -773,6 +936,9 @@ async function main() {
                     console.error('  cog registry categories  List categories');
                     console.error('  cog registry info <mod>  Show module details');
                     console.error('  cog registry refresh     Refresh cache');
+                    console.error('  cog registry build       Build registry tarballs + v2 index (local)');
+                    console.error('  cog registry verify      Verify local tarballs against v2 index');
+                    console.error('  cog registry verify --remote --index <url>  Verify remote index+tarballs');
                     process.exit(1);
                 }
                 break;
@@ -800,6 +966,7 @@ USAGE:
   cog <command> [options]
 
 COMMANDS:
+  core <cmd>          Minimal "one-file" workflow (new, schema, run)
   run <module>        Run a Cognitive Module
   test <module>       Run golden tests for a module
   compose <module>    Execute a composed module workflow
@@ -810,7 +977,7 @@ COMMANDS:
   remove <module>     Remove installed module
   versions <url>      List available versions
   search [query]      Search modules in registry
-  registry <cmd>      Registry commands (list, categories, info, refresh)
+  registry <cmd>      Registry commands (list, categories, info, refresh, build, verify)
   validate <module>   Validate module structure
   migrate <module>    Migrate module to v2.2 format
   pipe                Pipe mode (stdin/stdout)
@@ -820,6 +987,9 @@ COMMANDS:
   doctor              Check environment and configuration
 
 OPTIONS:
+  --profile <name>     Progressive complexity profile: core|default|strict|certified
+  --validate <mode>    Validation mode: auto|on|off (overrides --no-validate)
+  --audit              Write an audit record to ~/.cognitive/audit/ (stderr prints path)
   -a, --args <str>      Arguments to pass to module
   -i, --input <json>    JSON input for module
   -m, --module <name>   Module path within repo (for add)
@@ -831,6 +1001,8 @@ OPTIONS:
   --pretty              Pretty-print JSON output
   -V, --verbose         Verbose output
   --no-validate         Skip schema validation
+  --stdin               Read module prompt from stdin (for core run)
+  --force               Overwrite target directory (for core promote)
   -H, --host <host>     Server host (default: 0.0.0.0)
   -P, --port <port>     Server port (default: 8000)
   -d, --max-depth <n>   Max composition depth (default: 5)
@@ -842,11 +1014,21 @@ OPTIONS:
   --all                 Process all modules (for validate/migrate)
   -f, --format <fmt>    Output format: text or json (for validate)
   -c, --category <cat>  Filter by category (for search)
+  --registry <url>      Override registry index URL (or set env COGNITIVE_REGISTRY_URL)
+  --registry-timeout-ms <ms>  Registry index fetch timeout (overrides env COGNITIVE_REGISTRY_TIMEOUT_MS)
+  --registry-max-bytes <n>    Registry index max bytes (overrides env COGNITIVE_REGISTRY_MAX_BYTES)
   -l, --limit <n>       Limit results (for search, versions)
   -v, --version         Show version
   -h, --help            Show this help
 
 EXAMPLES:
+  # One-file Core (no registry required)
+  cog core new demo.md
+  cog core run demo.md --args "hello" --pretty
+  cog core schema demo.md --pretty
+  cog core promote demo.md
+  cog core promote demo.md ./cognitive/modules/demo
+
   # Search and discover modules
   cog search code review           # Search by keywords
   cog search                       # List all available modules
@@ -905,6 +1087,9 @@ ENVIRONMENT:
   DASHSCOPE_API_KEY   Alibaba Qwen (通义千问)
   OLLAMA_HOST         Ollama local (default: localhost:11434)
   COG_MODEL           Override default model for any provider
+  COGNITIVE_REGISTRY_URL  Override registry index URL
+  COGNITIVE_REGISTRY_TIMEOUT_MS  Registry index fetch timeout (ms)
+  COGNITIVE_REGISTRY_MAX_BYTES   Registry index max bytes
 `);
 }
 main().catch(e => {