dxcomplete 0.1.0

package/.env.example

@@ -0,0 +1,11 @@
+# Central service deployment
+DXC_MONGODB_URI=
+DXC_DATABASE_NAME=dxcomplete
+DXC_GOOGLE_CLIENT_ID=
+DXC_GOOGLE_CLIENT_SECRET=
+DXC_SERVICE_PROVISIONING_SECRET=
+
+# Workspace MCP deployment
+DXC_SERVICE_URL=
+DXC_SERVICE_CLIENT_ID=
+DXC_SERVICE_CLIENT_SECRET=

package/README.md

@@ -0,0 +1,215 @@
+# DX Complete
+
+DX Complete is an exploratory npm package for installing a reusable documentation, process, and MCP route kit into a Next.js workspace project.
+
+The broader product premise is:
+
+```text
+DX Complete = Decision Basis + Complete Engineering + Operations Measurement
+```
+
+The target command is:
+
+```sh
+npx dxcomplete init
+```
+
+The scaffold is intended to help a team describe and revise a full engineering and service lifecycle model. It deliberately does not present the current model as decided. Roles, workflows, object taxonomy, and diagrams are draft material that should be edited as the operating model becomes clearer.
+
+## Product Outcome
+
+Running `dxcomplete init` in a Next.js project creates an editable starting point for process documentation, Mermaid diagrams, taxonomy files, decision-basis templates, cost-model templates, workflow templates, placeholder controls, evidence folders, workspace configuration, Next-compatible MCP route wrappers, and optional GitHub workflow checks.
+
+The current draft model covers:
+
+- Direction
+- Product definition
+- Engineering execution
+- Engineer implementation, including Codex-assisted work where appropriate
+- QA verification
+- Product validation
+- Change and release control
+- Deployment
+- Operation
+- User support
+- Administration as part of operation
+- Audit and evidence
+
+## Current Framing
+
+The working hypothesis is that DX Complete describes a full decision-basis, engineering, and service lifecycle, not only software development. It includes cost and benefit reasoning before engineering begins, both build/change responsibilities and run/service responsibilities, and actual measurement after delivery where available.
+
+The current role model includes Owner, Engineer, Tester, Operator, Support Agent, and End User. The model keeps outcome authority, requirements, product validation, and risk acceptance visible inside Owner; implementation responsibilities inside Engineer; and administration responsibilities inside Operator.
+
+Current draft concepts include Workspace, Statement, Expectation, Requirement, Commitment, Deferral, Task, Environment, Component, Estimate, Benefits, Feedback, AuthoritativeRequest, FeatureRequest, Change, Incident, Problem, SupportTicket, Release, Deployment, Decision, Risk, and Control. These are represented in editable YAML and Markdown so they can evolve.
+
+## Usage
+
+Install the scaffold into the current Next.js project:
+
+```sh
+npx dxcomplete init
+```
+
+Install into another directory:
+
+```sh
+npx dxcomplete init --target ./some-project
+```
+
+Preview without writing files:
+
+```sh
+npx dxcomplete init --dry-run
+```
+
+Preview compatibility-critical scaffold updates for an installed workspace:
+
+```sh
+npx dxcomplete upgrade
+```
+
+Apply those updates:
+
+```sh
+npx dxcomplete upgrade --apply
+```
+
+Validate the scaffold shape:
+
+```sh
+npx dxcomplete validate
+```
+
+By default, the scaffold is written to `dxcomplete/` and a placeholder workflow is written to `.github/workflows/dxcomplete.yml`. Existing files are not overwritten unless `--force` is provided.
+
+`dxcomplete upgrade` previews by default. It manages the installed route wrappers, Vercel compatibility configuration, and `dxcomplete/.install-manifest.json`. It does not overwrite `dxcomplete/workspace.json`. It reports drift in `dxcomplete/docs` and `dxcomplete/process` because those files are expected to become user-owned after installation.
+Run `dxcomplete init` before `dxcomplete upgrade`; upgrade refuses targets that do not already have `dxcomplete/workspace.json`.
+
+The installed MCP route wrappers are written under `pages/api/` so the workspace can remain a normal Next.js app on Vercel:
+
+```text
+pages/api/mcp.js
+pages/api/dxcomplete.js
+pages/api/dxcomplete/[...path].js
+pages/api/auth/callback/google.js
+```
+
+The workspace identity is written to `dxcomplete/workspace.json` inside the installed project. That file belongs to the workspace app repo, not to the central DX Complete repo.
+
+## Package and Compatibility Versioning
+
+DX Complete uses one package version, one workspace compatibility gate, and one surface fingerprint:
+
+- `packageVersion` is the npm package release version from `package.json`.
+- `workspaceCompatibility` is the installed workspace compatibility gate. It changes only when an installed workspace must update its route/proxy surface to keep talking safely to the central service.
+- `surfaceFingerprint` is an automatic hash of the live MCP tools, tool schemas, process guide, and on-demand doc references. It can change without requiring a package release or workspace upgrade.
+
+The MCP `surfaceVersion` field is a stable surface identifier. Use `surfaceFingerprint` for exact surface reconciliation and `workspaceCompatibility` for upgrade decisions.
+
+## Runtime Dogfood
+
+The documentation scaffold is the first milestone. The next layer is a hosted runtime and MCP server so DX Complete can coordinate its own records. The runtime now treats Workspace as the boundary for one service scope.
+
+The default MCP deployment model is one endpoint per workspace. A Next.js project repo installs DX Complete and exposes an MCP route for that workspace, but that workspace server does not open the database directly. It proxies auth and MCP requests to the central DX Complete service. Access is scoped by the installed repo's `dxcomplete/workspace.json`, authenticated actor identity, and workspace membership. Do not use a workspace environment variable for this boundary.
+
+For the central service deployment, provide the database and Google OAuth configuration:
+
+```sh
+DXC_MONGODB_URI=mongodb+srv://...
+DXC_DATABASE_NAME=dxcomplete
+DXC_GOOGLE_CLIENT_ID=...
+DXC_GOOGLE_CLIENT_SECRET=...
+DXC_SERVICE_PROVISIONING_SECRET=...
+```
+
+`DXC_MONGODB_URI` is a secret, `DXC_DATABASE_NAME` is environment-specific, `DXC_GOOGLE_CLIENT_ID` is a provisioning detail, `DXC_GOOGLE_CLIENT_SECRET` is a secret, and `DXC_SERVICE_PROVISIONING_SECRET` is a secret.
+
+For a workspace MCP deployment, provide only the central-service connection:
+
+```sh
+DXC_SERVICE_URL=https://dxcomplete.example
+DXC_SERVICE_CLIENT_ID=...
+DXC_SERVICE_CLIENT_SECRET=...
+```
+
+`DXC_SERVICE_URL` is environment-specific, `DXC_SERVICE_CLIENT_ID` is a provisioning detail, and `DXC_SERVICE_CLIENT_SECRET` is a secret. Workspace MCP deployments must not require `DXC_MONGODB_URI`, `DXC_GOOGLE_CLIENT_ID`, or `DXC_GOOGLE_CLIENT_SECRET`.
+
+Then build and check the runtime:
+
+```sh
+npm run build
+npm run runtime:check
+```
+
+The first runtime collections cover workspaces, statements, journal entries, environments, components, estimates, benefits, expectations, requirements, commitments, deferrals, tasks, changes, decisions, and risks. Dogfooding should use the normal MCP tools to create and link those records inside the intended workspace. Workspace-scoped lifecycle records receive a human-readable reference such as `REQ-0001` while UUID remains the primary key and link target.
+
+Environment and Component records form the Operational Registry. The registry is an inventory of operational state: what exists in each environment, where it lives, and which secret names or locations are relevant. It is not monitoring, diagnostics, a secret vault, an event log, or a runbook engine. Secret pointers should identify stores and keys only; do not record secret values.
+
+Useful MCP tools for dogfooding include:
+
+- `runtime_status` to confirm the connected server process and MCP surface fingerprint.
+- `get_process_guide` to give MCP clients the current phase guide: Orient, Elicit, Weigh, Build, Go Live, Operate, and Measure.
+- `get_doc` to retrieve richer reference content for outcomes, flow, records, roles, and glossary terms on demand.
+- `create_dxcomplete_ticket`, `append_dxcomplete_ticket`, `list_dxcomplete_tickets`, and `archive_dxcomplete_ticket` for private, appendable DX Complete Tickets from the current actor.
+- `list_unread_dxcomplete_ticket_replies` to see which tickets have unread DX Complete replies without returning the reply body, and `read_dxcomplete_ticket` to open a ticket and mark those replies read.
+- `append_journal_note`, `read_journal`, `get_journal_entry`, and `append_journal_summary` for shared workspace context that has no dedicated record home.
+- `get_record`, `list_records`, and `list_linked_records` to inspect records and relationships.
+- `create_workspace`, `create_statement`, and `update_statement` to establish the workspace, service scope, and traceable source wording.
+- `create_environment`, `update_environment`, `list_environments`, `create_component`, `update_component`, and `list_components` for the Operational Registry.
+- `create_expectation` and `update_expectation` for user-facing conditions of satisfaction, with prior versions preserved on update.
+- `create_requirement` and `update_requirement` for requirement work, with prior requirement versions preserved on update.
+- `create_task` and `append_task_entry` for task work, where current status comes from the latest status-change entry.
+- `create_estimate` and `update_estimate` for itemized cost estimates used during Weigh, with prior versions preserved on update.
+- `create_benefits` and `update_benefits` for Owner-authored Benefits records used during Weigh, with prior versions preserved on update.
+- `create_commitment` and `create_deferral` for recording the Owner's Weigh outcome.
+- `append_deferral_event` for condition updates, notes, resolution into Commitment, or abandonment.
+- `create_decision` and `append_decision_entry` for recording revisitable choices, arguments, notes, and later decision entries.
+- `link_decision_input` for linking a Decision to the records that informed it.
+- `link_records` and `unlink_records` for explicit relationships when a typed tool does not already create or remove the link.
+- `archive_record` for cleanup without deleting evidence.
+
+Hosted MCP is exposed at `/api/mcp`. The workspace route uses Streamable HTTP, advertises OAuth metadata for remote MCP clients, proxies OAuth through the central service, sends users through Google OAuth, and then returns DX Complete bearer tokens scoped to the configured workspace. The installed repo supplies workspace identity through `dxcomplete/workspace.json`; the central service stores workspace memberships and executes MCP tools. The current dogfood workspace grants Owner access to `sam.bourque@gmail.com`.
+
+The central service exposes internal routes under `/api/dxcomplete/service/*`. Workspace servers authenticate to those routes with `DXC_SERVICE_CLIENT_ID` and `DXC_SERVICE_CLIENT_SECRET`. The provisioning route creates the workspace record, seeds the Owner membership, and returns the one-time workspace service-client secret.
+
+For Google OAuth provisioning, set the callback URL to `/api/auth/callback/google` on the hosted workspace domain. For the dogfood deployment, use `https://dxcomplete.directeddomains.com/api/auth/callback/google`.
+
+Use `runtime_status` to reconcile the MCP-facing contract. `surfaceFingerprint` is the single client-facing identity for the tools, tool schemas, process guide, and on-demand doc references together. `get_process_guide` and `get_doc` return the same `surfaceVersion` and `surfaceFingerprint`, so an MCP client can treat a mismatch as a stale or inconsistent surface and refresh before continuing.
+
+On Vercel, `vercel.json` must include `dxcomplete/workspace.json` in the API function bundle. The scaffold includes this by default with `functions["pages/api/**/*.js"].includeFiles`. Vercel reserves `/.well-known`, so the installed Next app rewrites the OAuth discovery metadata paths to the DX Complete route wrapper.
+
+A DX Complete Ticket is the private place for an MCP client user to raise a question, report, request, correction, or follow-up with DX Complete. It has an ID and can receive appended entries over time. The durable content is the title plus entries; summary is optional and is not generated automatically. DX Complete replies can be tracked as unread or read by the submitting actor. The unread list identifies tickets that need attention; reading the ticket opens the full content and marks addressed replies read. A ticket does not ingest files or assets, and does not automatically create a requirement, task, incident, or decision. Formal shared work should be created or linked separately when someone decides the ticket needs process follow-up.
+
+The Journal is shared workspace context, not a private ticket. It is for useful notes that do not already belong in a dedicated record such as Statement, Expectation, Requirement, Decision, Risk, Change, or Task. The routing test is: will another record reference or depend on this? If yes, prefer a dedicated record. Journal content that becomes load-bearing should be promoted to the appropriate record and linked back where useful. Journal entries are append-only and can be linked as decision inputs or provenance. The default journal read returns the hot tier: active summaries plus active raw notes. Summary entries point back to covered raw notes, and covered notes are archived out of the hot read without being deleted.
+
+For dogfood maintenance work that needs direct database access, batch the work in one process instead of running repeated one-off Mongo commands:
+
+```sh
+npm run dogfood:work-order -- --plan ./work-order.json
+```
+
+The work-order runner opens one runtime connection, runs ticket summaries, ticket reads, DX Complete replies, simple archives, link-residue checks, or a local one-off module, then closes the connection. It is a maintainer tool for dogfood cleanup and migration work; the normal product path remains the hosted MCP tools.
+
+Run the hosted MCP smoke test after runtime changes:
+
+```sh
+npm run smoke:mcp:http
+```
+
+After updating a remote connector, compare its `runtime_status` fingerprint with the hosted smoke-test fingerprint before relying on newly added tools.
+
+## Repository Structure
+
+```text
+docs/                 Package documentation and draft model notes
+templates/process/    Installed process scaffold
+templates/next/       Installed Next.js route wrappers
+templates/github/     Optional GitHub workflow placeholder
+src/                  TypeScript CLI, runtime, and MCP source
+dist/                 Runtime JavaScript CLI
+```
+
+## Design Principle
+
+Use the scaffold to preserve the current thinking without freezing it. Prefer explicit draft status, open questions, TODOs, and editable configuration over hardcoded claims about how the model must work.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+import { initProject } from "./init.js";
+import { checkRuntime } from "./runtime/check.js";
+import { upgradeProject } from "./upgrade.js";
+import { validateScaffold } from "./validate.js";
+import { DXCOMPLETE_PACKAGE_VERSION } from "./version.js";
+main(process.argv.slice(2)).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`dxcomplete: ${message}`);
+    process.exitCode = 1;
+});
+async function main(argv) {
+    const args = parseArgs(argv);
+    if (args.version) {
+        console.log(DXCOMPLETE_PACKAGE_VERSION);
+        return;
+    }
+    if (args.help || !args.command) {
+        printHelp();
+        return;
+    }
+    if (args.command === "init") {
+        const result = await initProject({
+            targetDir: args.targetDir,
+            force: args.force,
+            dryRun: args.dryRun,
+            includeGithubWorkflow: args.includeGithubWorkflow
+        });
+        if (args.dryRun) {
+            console.log(`Would initialize DX Complete scaffold in ${result.targetDir}`);
+            printList("Would write", result.planned);
+            printList("Would skip existing", result.skipped);
+            return;
+        }
+        console.log(`Initialized DX Complete scaffold in ${result.targetDir}`);
+        printList("Written", result.written);
+        printList("Skipped existing", result.skipped);
+        console.log("Review dxcomplete/docs/open-questions.md before treating the draft model as policy.");
+        return;
+    }
+    if (args.command === "upgrade") {
+        const result = await upgradeProject({
+            targetDir: args.targetDir,
+            apply: args.apply,
+            force: args.force
+        });
+        if (args.apply) {
+            console.log(result.manualReview.length > 0
+                ? `DX Complete upgrade requires manual review in ${result.targetDir}`
+                : `Upgraded DX Complete scaffold in ${result.targetDir}`);
+            printList("Written", result.written);
+            printList("Already current", result.unchanged);
+            printList("Manual review required", result.manualReview);
+            printList("User-owned scaffold drift", result.userOwnedDrift);
+            if (result.manualReview.length > 0) {
+                process.exitCode = 1;
+            }
+            return;
+        }
+        console.log(`Would upgrade DX Complete scaffold in ${result.targetDir}`);
+        console.log(`Package version ${result.packageVersion}; workspace compatibility ${result.workspaceCompatibility}.`);
+        printList("Would write", result.planned);
+        printList("Already current", result.unchanged);
+        printList("Manual review required", result.manualReview);
+        printList("User-owned scaffold drift", result.userOwnedDrift);
+        console.log("Run dxcomplete upgrade --apply to write compatibility-critical scaffold updates.");
+        return;
+    }
+    if (args.command === "validate") {
+        const result = await validateScaffold({
+            targetDir: args.targetDir,
+            packageLayout: args.packageLayout
+        });
+        if (result.ok) {
+            console.log(`DX Complete scaffold shape is valid in ${result.targetDir}`);
+            return;
+        }
+        console.error(`DX Complete scaffold is missing ${result.missing.length} required file(s):`);
+        for (const file of result.missing) {
+            console.error(`- ${file}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    if (args.command === "check-runtime") {
+        const result = await checkRuntime({ envFile: args.envFile });
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    throw new Error(`Unknown command "${args.command}".`);
+}
+function parseArgs(argv) {
+    const parsed = {
+        targetDir: process.cwd(),
+        force: false,
+        dryRun: false,
+        apply: false,
+        includeGithubWorkflow: true,
+        packageLayout: false,
+        help: false,
+        version: false
+    };
+    const positionals = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--help" || arg === "-h") {
+            parsed.help = true;
+            continue;
+        }
+        if (arg === "--apply") {
+            parsed.apply = true;
+            continue;
+        }
+        if (arg === "--version" || arg === "-v") {
+            parsed.version = true;
+            continue;
+        }
+        if (arg === "--target") {
+            const value = argv[index + 1];
+            if (!value) {
+                throw new Error("--target requires a directory.");
+            }
+            parsed.targetDir = value;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--target=")) {
+            parsed.targetDir = arg.slice("--target=".length);
+            continue;
+        }
+        if (arg === "--env") {
+            const value = argv[index + 1];
+            if (!value) {
+                throw new Error("--env requires a file path.");
+            }
+            parsed.envFile = value;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--env=")) {
+            parsed.envFile = arg.slice("--env=".length);
+            continue;
+        }
+        if (arg === "--force") {
+            parsed.force = true;
+            continue;
+        }
+        if (arg === "--dry-run") {
+            parsed.dryRun = true;
+            continue;
+        }
+        if (arg === "--no-github-workflow") {
+            parsed.includeGithubWorkflow = false;
+            continue;
+        }
+        if (arg === "--package-layout") {
+            parsed.packageLayout = true;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            throw new Error(`Unknown option "${arg}".`);
+        }
+        positionals.push(arg);
+    }
+    parsed.command = positionals[0];
+    if (positionals.length > 1) {
+        throw new Error(`Unexpected argument "${positionals[1]}".`);
+    }
+    if (parsed.apply && parsed.command !== "upgrade") {
+        throw new Error("--apply is only supported by upgrade.");
+    }
+    if (parsed.command === "upgrade" && parsed.apply && parsed.dryRun) {
+        throw new Error("upgrade cannot combine --apply and --dry-run.");
+    }
+    return parsed;
+}
+function printHelp() {
+    console.log(`dxcomplete
+
+Usage:
+  dxcomplete init [--target <dir>] [--force] [--dry-run] [--no-github-workflow]
+  dxcomplete upgrade [--target <dir>] [--apply] [--force]
+  dxcomplete validate [--target <dir>]
+  dxcomplete check-runtime [--env <file>]
+
+Commands:
+  init            Install the editable draft scaffold into a project.
+  upgrade         Preview or apply compatibility-critical scaffold updates.
+  validate        Validate the expected scaffold file shape.
+  check-runtime   Verify MongoDB connectivity and required collections.
+
+Options:
+  --target <dir>          Target project directory. Defaults to the current directory.
+  --env <file>            Runtime env file. Defaults to .env.local when present.
+  --apply                 Write upgrade changes. Upgrade previews by default.
+  --force                 Overwrite existing scaffold files.
+  --dry-run               Show what would be written without changing files.
+  --no-github-workflow    Skip installing .github/workflows/dxcomplete.yml.
+  --package-layout        Validate this package repository layout instead of an installed scaffold.
+  --help                  Show help.
+  --version               Show version.
+`);
+}
+function printList(label, values) {
+    if (values.length === 0) {
+        return;
+    }
+    console.log(`${label}:`);
+    for (const value of values) {
+        console.log(`- ${value}`);
+    }
+}

package/dist/http/server.d.ts

@@ -0,0 +1,7 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare function configureDxcompleteWorkspace(config: unknown): void;
+export declare function closeDxcompleteHttpRuntime(): Promise<void>;
+export default function handleDxcompleteHttpRequest(req: IncomingMessage & {
+    body?: unknown;
+    query?: Record<string, unknown>;
+}, res: ServerResponse): Promise<void>;