mcoda 0.1.37 → 0.1.40

package/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 - Initial npm packaging scaffold for the mcoda CLI.
+- Added bundled mswarm consent terms plus guided `mcoda setup`/postinstall consent bootstrap for installed CLI packages.
 
 ## 0.1.9
 - Release v0.1.9.

package/MSWARM_DATA_COLLECTION_TERMS.md

@@ -0,0 +1,65 @@
+Mswarm Data Collection Terms And Consent
+
+Version: 2026-03-18
+
+By using Docdex or mcoda with mswarm-backed services, you agree to the following terms.
+
+## What We Collect
+
+We may collect and process:
+
+- product installation and client identity metadata
+- consent records, including acceptance time, source IP address, and user agent
+- web search queries and web search results generated by the product
+- fetched webpage content and ai-digested summaries generated from that content
+- local delegation failures and related error diagnostics
+- mcoda local and cloud agent ratings, evaluations, and performance signals
+- package integrity metadata such as signatures, checksums, and upload timestamps
+
+## Why We Collect It
+
+We use this data to:
+
+- operate and improve mswarm-backed search, cache, and cloud features
+- measure quality, reliability, performance, and cost
+- detect abuse, fraud, tampering, or manipulated uploads
+- validate user consent and maintain compliance records
+- improve model ratings and answer-cache quality across the product ecosystem
+
+## Required Consent
+
+- Consent is required to use the product.
+- If you do not accept these terms, installation and setup cannot continue.
+- Your consent is recorded server-side together with the acceptance timestamp and source IP address.
+
+## Local Storage
+
+Before upload, the product stores telemetry locally under `~/.docdex` or `~/.mcoda`.
+Local packages may include search, fetch, answer, error, and rating data until they are uploaded or purged.
+
+## Upload And Retention
+
+- Telemetry packages are compressed, checksummed, and signed before upload.
+- The product retries failed uploads automatically.
+- Uploaded packages are deleted locally after successful transfer.
+- Unsent local packages older than 30 days are deleted.
+
+## Security And Integrity
+
+- Packages are signed to reduce the risk of tampering or malware injection.
+- Checksums are verified before ingestion.
+- mswarm may reject packages that fail integrity or policy checks.
+
+## Your Rights
+
+Subject to applicable law, you may:
+
+- withdraw consent for future collection
+- request deletion of your stored data
+- ask for a summary of data associated with your client identity
+
+Withdrawing consent stops future uploads but may also limit or disable product functionality that depends on mswarm.
+
+## Contact And Updates
+
+These terms may be updated. The product may require renewed acceptance when the policy version changes.

package/README.md

@@ -5,10 +5,13 @@ mcoda is a local-first CLI for planning, documentation, and execution workflows
 ## Install
 - Requires Node.js >= 20.
 - Global install: `npm i -g mcoda`
+- Interactive installs show the bundled mswarm data collection terms and require acceptance before setup can continue.
+- If install cannot prompt, complete the same mandatory consent flow with `mcoda setup` before other commands.
 - Verify: `mcoda --version`
 
 ## Quick start
 ```sh
+mcoda setup
 mcoda set-workspace --workspace-root .
 mcoda docs pdr generate --workspace-root . --project WEB --rfp-path docs/rfp/web.md --agent codex
 ```

package/dist/bin/McodaEntrypoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"McodaEntrypoint.d.ts","sourceRoot":"","sources":["../../src/bin/McodaEntrypoint.ts"],"names":[],"mappings":";AA+BA,qBAAa,eAAe;WACb,GAAG,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC;CAuMxE"}
+{"version":3,"file":"McodaEntrypoint.d.ts","sourceRoot":"","sources":["../../src/bin/McodaEntrypoint.ts"],"names":[],"mappings":";AAoCA,qBAAa,eAAe;WACb,GAAG,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC;CA6OxE"}

package/dist/bin/McodaEntrypoint.js

@@ -1,53 +1,58 @@
 #!/usr/bin/env node
-import { realpathSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import packageJson from "../../package.json" with { type: "json" };
-import { AgentsCommands } from "../commands/agents/AgentsCommands.js";
-import { GatewayAgentCommand } from "../commands/agents/GatewayAgentCommand.js";
-import { DocsCommands } from "../commands/docs/DocsCommands.js";
-import { JobsCommands } from "../commands/jobs/JobsCommands.js";
-import { OpenapiCommands } from "../commands/openapi/OpenapiCommands.js";
-import { CreateTasksCommand } from "../commands/planning/CreateTasksCommand.js";
-import { RefineTasksCommand } from "../commands/planning/RefineTasksCommand.js";
-import { TaskSufficiencyAuditCommand } from "../commands/planning/TaskSufficiencyAuditCommand.js";
-import { SdsPreflightCommand } from "../commands/planning/SdsPreflightCommand.js";
-import { BacklogCommands } from "../commands/backlog/BacklogCommands.js";
-import { TaskShowCommands } from "../commands/backlog/TaskShowCommands.js";
-import { OrderTasksCommand } from "../commands/backlog/OrderTasksCommand.js";
-import { EstimateCommands } from "../commands/estimate/EstimateCommands.js";
-import { TelemetryCommands } from "../commands/telemetry/TelemetryCommands.js";
-import { WorkOnTasksCommand } from "../commands/work/WorkOnTasksCommand.js";
-import { GatewayTrioCommand } from "../commands/work/GatewayTrioCommand.js";
-import { AddTestsCommand } from "../commands/work/AddTestsCommand.js";
-import { CodeReviewCommand } from "../commands/review/CodeReviewCommand.js";
-import { QaTasksCommand } from "../commands/planning/QaTasksCommand.js";
-import { MigrateTasksCommand } from "../commands/planning/MigrateTasksCommand.js";
-import { UpdateCommands } from "../commands/update/UpdateCommands.js";
-import { RoutingCommands } from "../commands/routing/RoutingCommands.js";
-import { TestAgentCommand } from "../commands/agents/TestAgentCommand.js";
-import { AgentRunCommand } from "../commands/agents/AgentRunCommand.js";
-import { SetWorkspaceCommand } from "../commands/workspace/SetWorkspaceCommand.js";
-import { ProjectGuidanceCommand } from "../commands/workspace/ProjectGuidanceCommand.js";
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import packageJson from '../../package.json' with { type: 'json' };
+import { AgentsCommands } from '../commands/agents/AgentsCommands.js';
+import { CloudCommands } from '../commands/cloud/CloudCommands.js';
+import { ConfigCommands } from '../commands/config/ConfigCommands.js';
+import { ConsentCommands } from '../commands/consent/ConsentCommands.js';
+import { GatewayAgentCommand } from '../commands/agents/GatewayAgentCommand.js';
+import { DocsCommands } from '../commands/docs/DocsCommands.js';
+import { JobsCommands } from '../commands/jobs/JobsCommands.js';
+import { OpenapiCommands } from '../commands/openapi/OpenapiCommands.js';
+import { CreateTasksCommand } from '../commands/planning/CreateTasksCommand.js';
+import { RefineTasksCommand } from '../commands/planning/RefineTasksCommand.js';
+import { TaskSufficiencyAuditCommand } from '../commands/planning/TaskSufficiencyAuditCommand.js';
+import { SdsPreflightCommand } from '../commands/planning/SdsPreflightCommand.js';
+import { BacklogCommands } from '../commands/backlog/BacklogCommands.js';
+import { TaskShowCommands } from '../commands/backlog/TaskShowCommands.js';
+import { OrderTasksCommand } from '../commands/backlog/OrderTasksCommand.js';
+import { EstimateCommands } from '../commands/estimate/EstimateCommands.js';
+import { TelemetryCommands } from '../commands/telemetry/TelemetryCommands.js';
+import { WorkOnTasksCommand } from '../commands/work/WorkOnTasksCommand.js';
+import { GatewayTrioCommand } from '../commands/work/GatewayTrioCommand.js';
+import { AddTestsCommand } from '../commands/work/AddTestsCommand.js';
+import { CodeReviewCommand } from '../commands/review/CodeReviewCommand.js';
+import { QaTasksCommand } from '../commands/planning/QaTasksCommand.js';
+import { MigrateTasksCommand } from '../commands/planning/MigrateTasksCommand.js';
+import { UpdateCommands } from '../commands/update/UpdateCommands.js';
+import { RoutingCommands } from '../commands/routing/RoutingCommands.js';
+import { SetupCommand } from '../commands/setup/SetupCommand.js';
+import { TestAgentCommand } from '../commands/agents/TestAgentCommand.js';
+import { AgentRunCommand } from '../commands/agents/AgentRunCommand.js';
+import { SetWorkspaceCommand } from '../commands/workspace/SetWorkspaceCommand.js';
+import { ProjectGuidanceCommand } from '../commands/workspace/ProjectGuidanceCommand.js';
+import { MswarmConfigStore } from '@mcoda/core';
 export class McodaEntrypoint {
     static async run(argv = process.argv.slice(2)) {
         const applyCodexNoSandboxFlag = (value) => {
-            if (value === undefined || value === "") {
-                process.env.MCODA_CODEX_NO_SANDBOX = "1";
+            if (value === undefined || value === '') {
+                process.env.MCODA_CODEX_NO_SANDBOX = '1';
                 return;
             }
             const normalized = value.trim().toLowerCase();
-            if (["0", "false", "off", "no"].includes(normalized)) {
-                process.env.MCODA_CODEX_NO_SANDBOX = "0";
+            if (['0', 'false', 'off', 'no'].includes(normalized)) {
+                process.env.MCODA_CODEX_NO_SANDBOX = '0';
                 return;
             }
-            process.env.MCODA_CODEX_NO_SANDBOX = "1";
+            process.env.MCODA_CODEX_NO_SANDBOX = '1';
         };
         const filteredArgs = [];
         for (let i = 0; i < argv.length; i += 1) {
             const arg = argv[i];
-            if (arg === "--codex-no-sandbox") {
+            if (arg === '--codex-no-sandbox') {
                 const next = argv[i + 1];
-                if (next && !next.startsWith("--")) {
+                if (next && !next.startsWith('--')) {
                     applyCodexNoSandboxFlag(next);
                     i += 1;
                 }
@@ -56,170 +61,202 @@ export class McodaEntrypoint {
                 }
                 continue;
             }
-            if (arg.startsWith("--codex-no-sandbox=")) {
-                const [, raw] = arg.split("=", 2);
+            if (arg.startsWith('--codex-no-sandbox=')) {
+                const [, raw] = arg.split('=', 2);
                 applyCodexNoSandboxFlag(raw);
                 continue;
             }
             filteredArgs.push(arg);
         }
         const [command, ...rest] = filteredArgs;
-        const wantsJson = argv.some((arg) => arg === "--json" || arg.startsWith("--json="));
-        const wantsQuiet = argv.some((arg) => arg === "--quiet" || arg.startsWith("--quiet="));
+        const wantsJson = argv.some((arg) => arg === '--json' || arg.startsWith('--json='));
+        const wantsQuiet = argv.some((arg) => arg === '--quiet' || arg.startsWith('--quiet='));
         if (wantsJson || wantsQuiet) {
-            process.env.MCODA_STREAM_IO = "0";
-            process.env.MCODA_STREAM_IO_PROMPT = "0";
+            process.env.MCODA_STREAM_IO = '0';
+            process.env.MCODA_STREAM_IO_PROMPT = '0';
         }
         else if (process.env.MCODA_STREAM_IO === undefined) {
-            process.env.MCODA_STREAM_IO = "0";
+            process.env.MCODA_STREAM_IO = '0';
             if (process.env.MCODA_STREAM_IO_PROMPT === undefined) {
-                process.env.MCODA_STREAM_IO_PROMPT = "0";
+                process.env.MCODA_STREAM_IO_PROMPT = '0';
             }
         }
-        if (command === "--version" || command === "-v" || command === "version") {
+        if (command === '--version' || command === '-v' || command === 'version') {
             // Keep this simple so `mcoda --version` works even in thin installs.
             // eslint-disable-next-line no-console
-            console.log(packageJson.version ?? "dev");
+            console.log(packageJson.version ?? 'dev');
             return;
         }
         if (!command) {
-            throw new Error("Usage: mcoda <agent|gateway-agent|test-agent|agent-run|routing|docs|openapi|job|jobs|tokens|telemetry|create-tasks|migrate-tasks|refine-tasks|task-sufficiency-audit|sds-preflight|order-tasks|tasks|add-tests|work-on-tasks|gateway-trio|code-review|qa-tasks|backlog|task|task-detail|estimate|update|set-workspace|project-guidance|pdr|sds> [...args]\n" +
-                "Routing: use `mcoda routing defaults` to view/update workspace/global defaults, `mcoda routing preview|explain` to inspect agent selection/provenance (override → workspace_default → global_default).\n" +
-                "Aliases: `tasks order-by-deps` forwards to `order-tasks` (dependency-aware ordering), `task`/`task-detail` show a single task.\n" +
-                "Job commands (mcoda job --help for details): list|status|watch|logs|inspect|resume|cancel|tokens\n" +
-                "Jobs API required for job commands (set MCODA_API_BASE_URL/MCODA_JOBS_API_URL or workspace api.baseUrl). status/watch/logs exit non-zero on failed/cancelled jobs per SDS.");
+            throw new Error('Usage: mcoda <agent|cloud|cloud-agent|config|consent|setup|gateway-agent|test-agent|agent-run|routing|docs|openapi|job|jobs|tokens|telemetry|create-tasks|migrate-tasks|refine-tasks|task-sufficiency-audit|sds-preflight|order-tasks|tasks|add-tests|work-on-tasks|gateway-trio|code-review|qa-tasks|backlog|task|task-detail|estimate|update|set-workspace|project-guidance|pdr|sds> [...args]\n' +
+                'Setup: use `mcoda setup` after installation (or accept the postinstall prompt) to complete the mandatory mswarm telemetry consent flow.\n' +
+                'Config: use `mcoda config set mswarm-api-key <KEY>` to persist an encrypted mswarm API key in the resolved global mcoda config file.\n' +
+                'Consent: use `mcoda consent accept` before other commands if you need to complete consent outside the guided setup flow.\n' +
+                'Routing: use `mcoda routing defaults` to view/update workspace/global defaults, `mcoda routing preview|explain` to inspect agent selection/provenance (override → workspace_default → global_default).\n' +
+                'Cloud agents: use `mcoda cloud agent list|details|sync` to discover and materialize mswarm-managed remote agents.\n' +
+                'Aliases: `tasks order-by-deps` forwards to `order-tasks` (dependency-aware ordering), `task`/`task-detail` show a single task.\n' +
+                'Job commands (mcoda job --help for details): list|status|watch|logs|inspect|resume|cancel|tokens\n' +
+                'Jobs API required for job commands (set MCODA_API_BASE_URL/MCODA_JOBS_API_URL or workspace api.baseUrl). status/watch/logs exit non-zero on failed/cancelled jobs per SDS.');
+        }
+        if (!['config', 'consent', 'setup'].includes(command)) {
+            const consentState = await new MswarmConfigStore().readState();
+            const consentAccepted = Boolean(consentState.consentAccepted);
+            const consentTokenSet = Boolean(consentState.consentToken?.trim());
+            if (!consentAccepted || !consentTokenSet) {
+                throw new Error('Telemetry consent is required before using mcoda. Review the mswarm data collection terms and run `mcoda setup` or `mcoda consent accept`.');
+            }
         }
-        if (command === "agent") {
+        if (command === 'agent') {
             await AgentsCommands.run(rest);
             return;
         }
-        if (command === "gateway-agent") {
+        if (command === 'cloud') {
+            await CloudCommands.run(rest);
+            return;
+        }
+        if (command === 'config') {
+            await ConfigCommands.run(rest);
+            return;
+        }
+        if (command === 'consent') {
+            await ConsentCommands.run(rest);
+            return;
+        }
+        if (command === 'setup') {
+            await SetupCommand.run(rest);
+            return;
+        }
+        if (command === 'cloud-agent') {
+            await CloudCommands.run(['agent', ...rest]);
+            return;
+        }
+        if (command === 'gateway-agent') {
             await GatewayAgentCommand.run(rest);
             return;
         }
-        if (command === "test-agent") {
+        if (command === 'test-agent') {
             await TestAgentCommand.run(rest);
             return;
         }
-        if (command === "agent-run") {
+        if (command === 'agent-run') {
             await AgentRunCommand.run(rest);
             return;
         }
-        if (command === "routing") {
+        if (command === 'routing') {
             await RoutingCommands.run(rest);
             return;
         }
-        if (command === "docs") {
+        if (command === 'docs') {
             await DocsCommands.run(rest);
             return;
         }
-        if (command === "openapi-from-docs" || command === "openapi") {
+        if (command === 'openapi-from-docs' || command === 'openapi') {
             await OpenapiCommands.run(rest);
             return;
         }
-        if (command === "job" || command === "jobs") {
+        if (command === 'job' || command === 'jobs') {
             await JobsCommands.run(rest);
             return;
         }
-        if (command === "tokens") {
+        if (command === 'tokens') {
             await TelemetryCommands.runTokens(rest);
             return;
         }
-        if (command === "telemetry") {
+        if (command === 'telemetry') {
             await TelemetryCommands.runTelemetry(rest);
             return;
         }
-        if (command === "pdr" || command === "mcoda:pdr") {
-            await DocsCommands.run(["pdr", "generate", ...rest]);
+        if (command === 'pdr' || command === 'mcoda:pdr') {
+            await DocsCommands.run(['pdr', 'generate', ...rest]);
             return;
         }
-        if (command === "sds" || command === "mcoda:sds") {
+        if (command === 'sds' || command === 'mcoda:sds') {
             const [subcommand, ...tail] = rest;
-            if (subcommand === "generate" || subcommand === "suggestions") {
-                await DocsCommands.run(["sds", subcommand, ...tail]);
+            if (subcommand === 'generate' || subcommand === 'suggestions') {
+                await DocsCommands.run(['sds', subcommand, ...tail]);
             }
             else {
-                await DocsCommands.run(["sds", "generate", ...rest]);
+                await DocsCommands.run(['sds', 'generate', ...rest]);
             }
             return;
         }
-        if (command === "create-tasks") {
+        if (command === 'create-tasks') {
             await CreateTasksCommand.run(rest);
             return;
         }
-        if (command === "migrate-tasks") {
+        if (command === 'migrate-tasks') {
             await MigrateTasksCommand.run(rest);
             return;
         }
-        if (command === "refine-tasks") {
+        if (command === 'refine-tasks') {
             await RefineTasksCommand.run(rest);
             return;
         }
-        if (command === "task-sufficiency-audit") {
+        if (command === 'task-sufficiency-audit') {
             await TaskSufficiencyAuditCommand.run(rest);
             return;
         }
-        if (command === "sds-preflight") {
+        if (command === 'sds-preflight') {
             await SdsPreflightCommand.run(rest);
             return;
         }
-        if (command === "qa-tasks") {
-            if (rest.includes("--help") || rest.includes("-h")) {
+        if (command === 'qa-tasks') {
+            if (rest.includes('--help') || rest.includes('-h')) {
                 // eslint-disable-next-line no-console
-                console.log("Usage: mcoda qa-tasks [--workspace-root <path>] --project <PROJECT_KEY> [--task <TASK_KEY> ... | --epic <EPIC_KEY> | --story <STORY_KEY>] [--status <STATUS_FILTER>] [--limit N] [--mode auto|manual] [--profile <PROFILE_NAME>] [--level unit|integration|acceptance] [--test-command \"<CMD>\"] [--agent <NAME>] [--agent-stream true|false] [--resume <JOB_ID>] [--create-followup-tasks auto|none|prompt] [--result pass|fail] [--notes \"<text>\"] [--evidence-url \"<url>\"] [--dry-run] [--json]");
+                console.log('Usage: mcoda qa-tasks [--workspace-root <path>] --project <PROJECT_KEY> [--task <TASK_KEY> ... | --epic <EPIC_KEY> | --story <STORY_KEY>] [--status <STATUS_FILTER>] [--limit N] [--mode auto|manual] [--profile <PROFILE_NAME>] [--level unit|integration|acceptance] [--test-command "<CMD>"] [--agent <NAME>] [--agent-stream true|false] [--resume <JOB_ID>] [--create-followup-tasks auto|none|prompt] [--result pass|fail] [--notes "<text>"] [--evidence-url "<url>"] [--dry-run] [--json]');
                 return;
             }
             await QaTasksCommand.run(rest);
             return;
         }
-        if (command === "order-tasks") {
+        if (command === 'order-tasks') {
             await OrderTasksCommand.run(rest);
             return;
         }
-        if (command === "tasks") {
+        if (command === 'tasks') {
             const [sub, ...tail] = rest;
-            if (sub === "order-by-deps" || sub === "order-by-dependencies") {
+            if (sub === 'order-by-deps' || sub === 'order-by-dependencies') {
                 await OrderTasksCommand.run(tail);
                 return;
             }
         }
-        if (command === "work-on-tasks") {
+        if (command === 'work-on-tasks') {
             await WorkOnTasksCommand.run(rest);
             return;
         }
-        if (command === "add-tests") {
+        if (command === 'add-tests') {
             await AddTestsCommand.run(rest);
             return;
         }
-        if (command === "gateway-trio") {
+        if (command === 'gateway-trio') {
             await GatewayTrioCommand.run(rest);
             return;
         }
-        if (command === "code-review") {
+        if (command === 'code-review') {
             await CodeReviewCommand.run(rest);
             return;
         }
-        if (command === "backlog") {
+        if (command === 'backlog') {
             await BacklogCommands.run(rest);
             return;
         }
-        if (command === "task" || command === "task-detail") {
+        if (command === 'task' || command === 'task-detail') {
             await TaskShowCommands.run(rest);
             return;
         }
-        if (command === "estimate") {
+        if (command === 'estimate') {
             await EstimateCommands.run(rest);
             return;
         }
-        if (command === "update") {
+        if (command === 'update') {
             await UpdateCommands.run(rest);
             return;
         }
-        if (command === "set-workspace") {
+        if (command === 'set-workspace') {
             await SetWorkspaceCommand.run(rest);
             return;
         }
-        if (command === "project-guidance") {
+        if (command === 'project-guidance') {
             await ProjectGuidanceCommand.run(rest);
             return;
         }
@@ -227,7 +264,7 @@ export class McodaEntrypoint {
     }
 }
 const isDirectRun = (() => {
-    if (typeof process.argv[1] !== "string") {
+    if (typeof process.argv[1] !== 'string') {
         return false;
     }
     try {

package/dist/commands/cloud/CloudCommands.d.ts

@@ -0,0 +1,4 @@
+export declare class CloudCommands {
+    static run(argv: string[]): Promise<void>;
+}
+//# sourceMappingURL=CloudCommands.d.ts.map

package/dist/commands/cloud/CloudCommands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloudCommands.d.ts","sourceRoot":"","sources":["../../../src/commands/cloud/CloudCommands.ts"],"names":[],"mappings":"AAkNA,qBAAa,aAAa;WACX,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CA4FhD"}