dxcomplete 0.1.0

package/docs/workflows.md

@@ -0,0 +1,60 @@
+# Draft Workflows
+
+These workflows are editable drafts. They describe likely lifecycle paths without declaring them final.
+
+## Current Workflow Areas
+
+- Intake and triage
+- Decision basis
+- Statement and expectation capture
+- Requirement elicitation
+- Current-state cost context attempt
+- Itemized cost estimate
+- Benefits
+- Weigh outcome
+- Product definition
+- Engineering execution
+- QA verification
+- Product validation
+- Change and release control
+- Deployment and operations
+- Operational Registry maintenance
+- Support and incident management
+- Problem and improvement management
+- Risk and control management
+- Audit and evidence capture
+- Actual cost / benefit observations
+- Estimate refinement
+
+## Draft End-To-End Flow
+
+1. A signal enters through feedback, authoritative request, support ticket, incident, or strategic direction.
+2. Statement capture preserves the user's own words and links the work to the Workspace context.
+3. Orient captures statement, confirms wording before recording, and restates expectations with approval where needed.
+4. Elicitation translates expectations into requirements, dependencies, constraints, and unknowns.
+5. Engineer review notes can be added to expectations or requirements when input should stay visible.
+6. Current-state cost context is attempted. It may be complete, partial, unavailable, or undisclosed.
+7. An itemized cost Estimate is generated from the elicited requirement set where cost reasoning is needed.
+8. Benefits are captured where useful, including qualitative benefits when amounts are not available.
+9. A decision basis is prepared for Weigh, including important review notes where present, the Estimate and Benefits where considered, and any Decision entries or linked inputs that informed the outcome.
+10. Owner records a Commitment or a Deferral. If committing, Owner and Engineer move the committed requirement set into build planning. If deferring, the unmet conditions remain visible.
+11. Engineer implements tasks and may use Codex assistance where appropriate.
+12. Tester verifies completed work against requirements and acceptance criteria.
+13. Owner validates whether the result is the right outcome.
+14. Change and release control records the service change plan, execution steps, rollback path, notice, vetoes, emergency posture, and result.
+15. Operator carries out the change in external operational tooling, then monitors and runs the service.
+16. Environment and Component records are kept current when the operational inventory changes.
+17. Support Agent handles user-facing issues and routes signals back into Owner or Operator follow-up.
+18. Actual cost / benefit observations are captured where available.
+19. Audit evidence is captured across decisions, controls, releases, deployments, measurement, and verification.
+
+## Workflow Questions
+
+- Which steps require explicit approval?
+- Which steps can be combined for low-risk changes?
+- What cost visibility is enough to proceed when baseline data is unavailable?
+- How should proceeding past an open checkpoint be shown when the risk remains open?
+- What evidence is required before release?
+- What notice, veto, and emergency evidence is enough for a Change record?
+- What operational inventory belongs in Environment and Component records rather than Journal?
+- What is the smallest useful workflow for a solo project?

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "dxcomplete",
+  "version": "0.1.0",
+  "description": "Reusable DX Complete / Complete Engineering documentation and scaffold kit.",
+  "type": "module",
+  "bin": {
+    "dxcomplete": "dist/cli.js"
+  },
+  "exports": {
+    "./http": {
+      "types": "./dist/http/server.d.ts",
+      "default": "./dist/http/server.js"
+    },
+    "./service": {
+      "types": "./dist/http/service.d.ts",
+      "default": "./dist/http/service.js"
+    }
+  },
+  "files": [
+    ".env.example",
+    "dist",
+    "docs",
+    "scripts",
+    "src",
+    "templates",
+    "website",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc --noEmit -p tsconfig.json && node scripts/check-public-copy.mjs && node scripts/check-env-surface.mjs && node scripts/check-service-boundary.mjs",
+    "check:public-copy": "node scripts/check-public-copy.mjs",
+    "check:env-surface": "node scripts/check-env-surface.mjs",
+    "check:service-boundary": "node scripts/check-service-boundary.mjs",
+    "smoke:mcp:http": "node scripts/smoke-mcp-http.mjs --depth=light",
+    "smoke:mcp:http:light": "node scripts/smoke-mcp-http.mjs --depth=light",
+    "smoke:mcp:http:deep": "node scripts/smoke-mcp-http.mjs --depth=deep",
+    "smoke:mcp:http:full": "node scripts/smoke-mcp-http.mjs --depth=deep",
+    "smoke:mcp:http:surface": "node scripts/smoke-mcp-http.mjs --area=surface",
+    "smoke:mcp:http:docs": "node scripts/smoke-mcp-http.mjs --area=docs",
+    "smoke:mcp:http:records": "node scripts/smoke-mcp-http.mjs --area=records",
+    "smoke:mcp:http:weigh": "node scripts/smoke-mcp-http.mjs --area=weigh",
+    "smoke:mcp:http:change": "node scripts/smoke-mcp-http.mjs --area=change",
+    "smoke:mcp:http:tickets": "node scripts/smoke-mcp-http.mjs --area=tickets",
+    "smoke:mcp:http:journal": "node scripts/smoke-mcp-http.mjs --area=journal",
+    "dogfood:work-order": "node scripts/dogfood-work-order.mjs",
+    "validate:package": "node dist/cli.js validate --target . --package-layout",
+    "runtime:check": "node dist/cli.js check-runtime"
+  },
+  "engines": {
+    "node": "22.x"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "typescript": "^5.8.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "mongodb": "^7.2.0",
+    "zod": "^4.4.3"
+  }
+}

package/scripts/check-env-surface.mjs

@@ -0,0 +1,136 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const allowedEnvVars = new Map([
+  ["DXC_MONGODB_URI", "secret"],
+  ["DXC_DATABASE_NAME", "environment-specific value"],
+  ["DXC_GOOGLE_CLIENT_ID", "provisioning detail"],
+  ["DXC_GOOGLE_CLIENT_SECRET", "secret"],
+  ["DXC_SERVICE_PROVISIONING_SECRET", "secret"],
+  ["DXC_SERVICE_URL", "environment-specific value"],
+  ["DXC_SERVICE_CLIENT_ID", "provisioning detail"],
+  ["DXC_SERVICE_CLIENT_SECRET", "secret"]
+]);
+
+const allowedClassifications = new Set([
+  "secret",
+  "provisioning detail",
+  "environment-specific value"
+]);
+
+const scanTargets = [
+  ".env.example",
+  "README.md",
+  "AGENTS.md",
+  "package.json",
+  "api",
+  "scripts",
+  "src",
+  "dist",
+  "docs",
+  "templates",
+  "website"
+];
+
+const docEnvPattern = /\b[A-Z][A-Z0-9]+(?:_[A-Z0-9]+)+\b/g;
+const quotedEnvPattern = /["'`]([A-Z][A-Z0-9]+(?:_[A-Z0-9]+)+)["'`]/g;
+const failures = [];
+const references = new Map();
+
+for (const [name, classification] of allowedEnvVars) {
+  if (!allowedClassifications.has(classification)) {
+    failures.push(`${name}: invalid env classification "${classification}".`);
+  }
+}
+
+for (const target of scanTargets) {
+  const targetPath = path.join(rootDir, target);
+  if (!existsSync(targetPath)) continue;
+
+  for (const filePath of listFiles(targetPath)) {
+    scanFile(filePath);
+  }
+}
+
+for (const [name, locations] of references) {
+  if (!allowedEnvVars.has(name)) {
+    failures.push(
+      `${name}: referenced but not allowed. Add it to scripts/check-env-surface.mjs with classification secret, provisioning detail, or environment-specific value, or remove it. First seen at ${locations[0]}.`
+    );
+  }
+}
+
+if (failures.length > 0) {
+  console.error("Environment surface check failed:");
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log("Environment surface check passed.");
+
+function listFiles(targetPath) {
+  const stats = statSync(targetPath);
+  if (stats.isFile()) {
+    return shouldScan(targetPath) ? [targetPath] : [];
+  }
+
+  const files = [];
+  for (const entry of readdirSync(targetPath)) {
+    if (entry === "node_modules" || entry === ".git") continue;
+    files.push(...listFiles(path.join(targetPath, entry)));
+  }
+  return files;
+}
+
+function shouldScan(filePath) {
+  const relativePath = path.relative(rootDir, filePath);
+  if (relativePath === "package-lock.json") return false;
+
+  return [
+    ".example",
+    ".html",
+    ".js",
+    ".json",
+    ".md",
+    ".mjs",
+    ".ts",
+    ".yml",
+    ".yaml"
+  ].some((extension) => filePath.endsWith(extension));
+}
+
+function scanFile(filePath) {
+  const relativePath = path.relative(rootDir, filePath);
+  const content = readFileSync(filePath, "utf8");
+
+  if (relativePath === ".env.example") {
+    for (const [index, line] of content.split(/\r?\n/).entries()) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const key = trimmed.split("=", 1)[0]?.trim();
+      if (key) addReference(key, `${relativePath}:${index + 1}`);
+    }
+    return;
+  }
+
+  const isSourceLike = /\.(?:js|json|mjs|ts)$/.test(filePath);
+  const pattern = isSourceLike ? quotedEnvPattern : docEnvPattern;
+  pattern.lastIndex = 0;
+
+  for (const match of content.matchAll(pattern)) {
+    const name = isSourceLike ? match[1] : match[0];
+    addReference(name, relativePath);
+  }
+}
+
+function addReference(name, location) {
+  if (!references.has(name)) {
+    references.set(name, []);
+  }
+  references.get(name).push(location);
+}

package/scripts/check-public-copy.mjs

@@ -0,0 +1,263 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const websiteDir = path.join(rootDir, "website");
+
+const forbiddenPatterns = [
+  { pattern: /\bMermaid\b/i, reason: "Mermaid/source details are not public-facing copy." },
+  { pattern: /\bflowchart\b/i, reason: "Diagram source terms are not public-facing copy." },
+  { pattern: /\bdiagram source\b/i, reason: "Source labels are not public-facing copy." },
+  { pattern: /\bCLI\b/, reason: "Command-line internals do not belong in public website copy." },
+  { pattern: /\bMCP\b/, reason: "MCP internals do not belong in public website copy." },
+  { pattern: /\bMongoDB\b/, reason: "Storage internals do not belong in public website copy." },
+  { pattern: /\bnpx\b/i, reason: "Install command details do not belong in public website copy." },
+  { pattern: /\bcommand-line\b/i, reason: "Command-line internals do not belong in public website copy." },
+  { pattern: /\bbootstrap\b/i, reason: "Implementation language does not belong in public website copy." },
+  { pattern: /\bscaffold(?:ing)?\b/i, reason: "Scaffold language is maintainer-facing." },
+  { pattern: /\btemplates?\b/i, reason: "Template language is maintainer-facing." },
+  { pattern: /\bpackage\b/i, reason: "Package details are maintainer-facing." },
+  { pattern: /\bimplementation\b/i, reason: "Implementation mechanics are maintainer-facing." },
+  { pattern: /\bconfiguration\b/i, reason: "Configuration mechanics are maintainer-facing." },
+  { pattern: /\bdeveloper\b/i, reason: "Developer-facing language should stay out of public pages." },
+  { pattern: /\binternal\b/i, reason: "Internal-facing language should stay out of public pages." },
+  { pattern: /\bTODO\b/i, reason: "TODOs should not appear in public website copy." },
+  { pattern: /\bdraft\b/i, reason: "Draft labels should not appear in public website copy." },
+  { pattern: /\bplaceholder\b/i, reason: "Placeholder labels should not appear in public website copy." }
+];
+
+const htmlFiles = readdirSync(websiteDir)
+  .filter((file) => file.endsWith(".html"))
+  .sort();
+
+const jsFiles = readdirSync(websiteDir)
+  .filter((file) => file.endsWith(".js"))
+  .sort();
+
+const mdFiles = readdirSync(websiteDir)
+  .filter((file) => file.endsWith(".md"))
+  .sort();
+
+const failures = [];
+const alphabet = "abcdefghijklmnopqrstuvwxyz".split("");
+
+function visibleTextFromHtml(html) {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function addCopyFailures(file, text) {
+  for (const { pattern, reason } of forbiddenPatterns) {
+    const match = text.match(pattern);
+    if (match) {
+      failures.push({
+        file,
+        reason,
+        detail: `matched "${match[0]}"`
+      });
+    }
+  }
+}
+
+function addBrokenLinkFailures(file, html) {
+  const linkPattern = /href=["']\.\/([^"'#?]+\.html)(?:[?#][^"']*)?["']/g;
+  for (const match of html.matchAll(linkPattern)) {
+    const linkedFile = match[1];
+    const linkedPath = path.join(websiteDir, linkedFile);
+    if (!existsSync(linkedPath)) {
+      failures.push({
+        file,
+        reason: "Local website link points to a missing page.",
+        detail: linkedFile
+      });
+    }
+  }
+}
+
+function plainText(html) {
+  return html
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function normalizeTerm(term) {
+  return term.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+function compareTerms(left, right) {
+  return left.localeCompare(right, "en", { sensitivity: "base" });
+}
+
+function addGlossaryFailures() {
+  const glossaryFile = "glossary.html";
+  const glossarySource = readFileSync(path.join(websiteDir, glossaryFile), "utf8");
+  const sectionPattern = /<section id="([a-z])" class="glossary-letter">([\s\S]*?)<\/section>/g;
+  const sections = [...glossarySource.matchAll(sectionPattern)].map((match) => ({
+    id: match[1],
+    body: match[2]
+  }));
+  const sectionIds = sections.map((section) => section.id);
+  const expectedSectionIds = [...sectionIds].sort();
+
+  if (sectionIds.join("") !== expectedSectionIds.join("")) {
+    failures.push({
+      file: `website/${glossaryFile}`,
+      reason: "Glossary letter sections are not in alphabetical order.",
+      detail: sectionIds.join(", ")
+    });
+  }
+
+  const terms = [];
+  for (const section of sections) {
+    const sectionTerms = [...section.body.matchAll(/<dt>([\s\S]*?)<span>/g)]
+      .map((match) => plainText(match[1]));
+    const expectedTerms = [...sectionTerms].sort(compareTerms);
+
+    if (sectionTerms.join("||") !== expectedTerms.join("||")) {
+      failures.push({
+        file: `website/${glossaryFile}`,
+        reason: `Glossary terms under ${section.id.toUpperCase()} are not alphabetical.`,
+        detail: sectionTerms.join(", ")
+      });
+    }
+
+    for (const term of sectionTerms) {
+      if (term.charAt(0).toLowerCase() !== section.id) {
+        failures.push({
+          file: `website/${glossaryFile}`,
+          reason: "Glossary term appears under the wrong letter.",
+          detail: `${term} under ${section.id.toUpperCase()}`
+        });
+      }
+      terms.push(term);
+    }
+  }
+
+  const normalizedTerms = terms.map(normalizeTerm);
+  const duplicateTerms = normalizedTerms.filter((term, index) => normalizedTerms.indexOf(term) !== index);
+  for (const term of [...new Set(duplicateTerms)]) {
+    failures.push({
+      file: `website/${glossaryFile}`,
+      reason: "Glossary contains a duplicate term.",
+      detail: term
+    });
+  }
+
+  const linkLetters = [...glossarySource.matchAll(/<a href="#([a-z])">[A-Z]<\/a>/g)].map((match) => match[1]);
+  const disabledLetters = [...glossarySource.matchAll(/<span aria-disabled="true">([A-Z])<\/span>/g)].map((match) => match[1].toLowerCase());
+  const indexLetters = [...linkLetters, ...disabledLetters].sort();
+
+  if (indexLetters.join("") !== alphabet.join("")) {
+    failures.push({
+      file: `website/${glossaryFile}`,
+      reason: "Glossary A-Z index must include every letter exactly once.",
+      detail: indexLetters.join("")
+    });
+  }
+
+  for (const sectionId of sectionIds) {
+    if (!linkLetters.includes(sectionId)) {
+      failures.push({
+        file: `website/${glossaryFile}`,
+        reason: "Glossary A-Z index is missing a link for a populated letter.",
+        detail: sectionId.toUpperCase()
+      });
+    }
+  }
+
+  for (const disabledLetter of disabledLetters) {
+    if (sectionIds.includes(disabledLetter)) {
+      failures.push({
+        file: `website/${glossaryFile}`,
+        reason: "Glossary A-Z index disables a populated letter.",
+        detail: disabledLetter.toUpperCase()
+      });
+    }
+  }
+
+  const glossarySet = new Set(normalizedTerms);
+  for (const requiredTerm of publicTermsThatNeedGlossaryEntries()) {
+    if (!glossarySet.has(normalizeTerm(requiredTerm))) {
+      failures.push({
+        file: `website/${glossaryFile}`,
+        reason: "Glossary is missing a term used by the public website.",
+        detail: requiredTerm
+      });
+    }
+  }
+}
+
+function publicTermsThatNeedGlossaryEntries() {
+  const terms = new Set();
+
+  const recordsSource = readFileSync(path.join(websiteDir, "objects.html"), "utf8");
+  for (const match of recordsSource.matchAll(/<span class="record-name">([\s\S]*?)<\/span>/g)) {
+    terms.add(plainText(match[1]));
+  }
+  for (const match of recordsSource.matchAll(/<dt>([\s\S]*?)<\/dt>/g)) {
+    terms.add(plainText(match[1]));
+  }
+
+  for (const file of htmlFiles.filter((file) => file.startsWith("phase-"))) {
+    const source = readFileSync(path.join(websiteDir, file), "utf8");
+    const recordsMatch = source.match(/<h2>Records<\/h2>[\s\S]*?<ul>([\s\S]*?)<\/ul>/);
+    if (!recordsMatch) continue;
+    for (const match of recordsMatch[1].matchAll(/<li>([\s\S]*?)<\/li>/g)) {
+      terms.add(plainText(match[1]));
+    }
+  }
+
+  const rolesSource = readFileSync(path.join(websiteDir, "roles.html"), "utf8");
+  for (const match of rolesSource.matchAll(/<button[^>]*>([\s\S]*?)<\/button>/g)) {
+    terms.add(plainText(match[1]));
+  }
+
+  return [...terms].sort(compareTerms);
+}
+
+for (const file of htmlFiles) {
+  const source = readFileSync(path.join(websiteDir, file), "utf8");
+  addCopyFailures(`website/${file}`, visibleTextFromHtml(source));
+  addBrokenLinkFailures(`website/${file}`, source);
+}
+
+for (const file of jsFiles) {
+  const source = readFileSync(path.join(websiteDir, file), "utf8");
+  addCopyFailures(`website/${file}`, source);
+}
+
+for (const file of mdFiles) {
+  const source = readFileSync(path.join(websiteDir, file), "utf8");
+  addCopyFailures(`website/${file}`, source);
+}
+
+addGlossaryFailures();
+
+if (failures.length > 0) {
+  console.error("Public website copy check failed:");
+  for (const failure of failures) {
+    console.error(`- ${failure.file}: ${failure.reason} (${failure.detail})`);
+  }
+  process.exit(1);
+}
+
+console.log("Public website copy check passed.");

package/scripts/check-service-boundary.mjs

@@ -0,0 +1,63 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const workspaceBoundaryFiles = [
+  "src/http/server.ts",
+  "api/mcp.js",
+  "api/dxcomplete.js",
+  "api/auth/callback/google.js",
+  "templates/next/pages/api/mcp.js",
+  "templates/next/pages/api/dxcomplete.js",
+  "templates/next/pages/api/dxcomplete/[...path].js",
+  "templates/next/pages/api/auth/callback/google.js"
+];
+const bannedPatterns = [
+  {
+    pattern: /\bconnectRuntime\b/,
+    reason: "workspace MCP code must not open the runtime database"
+  },
+  {
+    pattern: /runtime\/mongo|runtime\\mongo|\.\.\/runtime\/mongo|\.\.\/dist\/runtime\/mongo/,
+    reason: "workspace MCP code must not import the Mongo runtime"
+  },
+  {
+    pattern: /runtime\/records|runtime\\records|\.\.\/runtime\/records|\.\.\/dist\/runtime\/records/,
+    reason: "workspace MCP code must not import runtime record modules"
+  },
+  {
+    pattern: /runtime\/auth|runtime\\auth|\.\.\/runtime\/auth|\.\.\/dist\/runtime\/auth/,
+    reason: "workspace MCP code must not import central auth/storage modules"
+  },
+  {
+    pattern: /\bDXC_MONGODB_URI\b/,
+    reason: "workspace MCP code must not reference Mongo credentials"
+  },
+  {
+    pattern: /\bDXC_GOOGLE_CLIENT_ID\b|\bDXC_GOOGLE_CLIENT_SECRET\b/,
+    reason: "workspace MCP code must not reference Google OAuth provisioning secrets"
+  }
+];
+const failures = [];
+
+for (const relativePath of workspaceBoundaryFiles) {
+  const absolutePath = path.join(rootDir, relativePath);
+  const content = readFileSync(absolutePath, "utf8");
+
+  for (const { pattern, reason } of bannedPatterns) {
+    if (pattern.test(content)) {
+      failures.push(`${relativePath}: ${reason}.`);
+    }
+  }
+}
+
+if (failures.length > 0) {
+  console.error("Service boundary check failed:");
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log("Service boundary check passed.");