mikoshi-construct 0.1.1 → 0.1.3

package/README.md

@@ -3,8 +3,10 @@
 Bootstrap for AI-native software projects. Start with a proven engineering workflow instead of an
 empty repository.
 
-```
-npx mikoshi-construct init
+```bash
+mkdir my-service && cd my-service
+npx mikoshi-construct init          # interactive: preset, agent, project name
+pnpm install && pnpm run quality    # green before you write a line
 ```
 
 > **v0.1.** Presets `node-backend`, `node-frontend`, `node-library` and `monorepo`. Claude Code gets
@@ -34,6 +36,52 @@ An existing repository gets the policy, the harness tooling and the agent files,
 code; its own `AGENTS.md`, `CLAUDE.md`, `package.json` and configs are merged or left alone, and
 `init` says what still has to be wired by hand.
 
+## Usage
+
+**A new project.** Name a preset and it writes everything:
+
+```bash
+mkdir my-service && cd my-service
+npx mikoshi-construct init --yes --preset node-backend
+pnpm install && pnpm run quality
+```
+
+**An existing repository.** Look before you write:
+
+```bash
+npx mikoshi-construct init --preset monorepo --dry-run
+```
+
+```
+  ~ package.json (merge)
+  = eslint.config.mjs — exists, review manually
+  + architecture/principles.md
+  + .claude/commands/construct-discover.md
+
+  Sample sources omitted: the directory is not empty. Discovery maps what is already here.
+```
+
+`+` creates a file that is not there. `~` merges into one that is, inside a
+`construct:begin … construct:end` block or as a JSON merge where your values win. `=` leaves the file
+alone and reports it. No example code lands in a repository that already has some, and there is no
+`--force`.
+
+**Cursor, or both agents.** The rules are written once and rendered for each:
+
+```bash
+npx mikoshi-construct init --yes --preset node-frontend --ai both
+```
+
+**Check a repository at any time.**
+
+```bash
+npx mikoshi-construct doctor     # baseline intact, harness intact, markers filled
+npx mikoshi-construct soulkill   # what the detector sees; writes nothing
+npx mikoshi-construct cost --last
+```
+
+Every command, flag and exit code: [docs/cli.md](https://github.com/E1i/mikoshi-construct/blob/main/docs/cli.md).
+
 ## Three principles
 
 1. **CLI detects facts. Agent interprets the system.** Everything that needs understanding of the
@@ -82,7 +130,8 @@ with a named check, not a second fix.
 | `construct soulkill` | Print what the detector sees, write nothing (`--json`; aliases `inspect`, `capture`) |
 | `construct cost` | Token usage of the `/implement` runs in this directory, per agent, billable and price-weighted (`--last`, `--json`) |
 
-`--plain` turns off colours and lore for CI. `--johnny` — wake up, Netrunner.
+`--plain` turns off colours and lore for CI. `--johnny` — wake up, Netrunner. The full reference,
+with examples and exit codes, is in [docs/cli.md](https://github.com/E1i/mikoshi-construct/blob/main/docs/cli.md).
 
 > If you already keep a user-level `implement` skill in `~/.claude/skills/`, it shadows the one the
 > construct puts in `.claude/skills/implement/`; move yours aside to run the repository's ladder.

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import path13 from "path";
+import path14 from "path";
 import process4 from "process";
 import { isTTY } from "@clack/prompts";
 import { defineCommand, runMain } from "citty";
@@ -269,11 +269,11 @@ function printDoctor(ui2, result) {
 
 // src/commands/init.ts
 import { mkdirSync as mkdirSync2 } from "fs";
-import path12 from "path";
+import path13 from "path";
 
 // src/detect/index.ts
-import { existsSync as existsSync7 } from "fs";
-import path7 from "path";
+import { existsSync as existsSync8 } from "fs";
+import path8 from "path";
 import process from "process";
 
 // src/detect/existing.ts
@@ -314,65 +314,109 @@ function detectExisting(dir) {
 }
 
 // src/detect/layout.ts
-import { existsSync as existsSync5, readdirSync as readdirSync4, readFileSync as readFileSync4, statSync as statSync2 } from "fs";
+import { existsSync as existsSync6, readdirSync as readdirSync4, readFileSync as readFileSync5, statSync as statSync2 } from "fs";
+import path6 from "path";
+
+// src/detect/workspaces.ts
+import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
 import path5 from "path";
-var IGNORED_ENTRIES = /* @__PURE__ */ new Set([".git", ".DS_Store", ".gitignore", ".gitattributes", "LICENSE", "README.md", ".idea", ".vscode"]);
-function isEmptyDir(dir) {
-  if (!existsSync5(dir))
-    return true;
-  return readdirSync4(dir).every((entry) => IGNORED_ENTRIES.has(entry));
+var TOP_LEVEL_PACKAGES_KEY = /^packages:(.*)$/m;
+var EMPTY_FLOW_SEQUENCE = /^\[\s*\]$/;
+var BLOCK_SEQUENCE_ENTRY = /^[ \t]+-[ \t]*\S/;
+function readIfPresent(file) {
+  if (!existsSync5(file))
+    return null;
+  try {
+    return readFileSync4(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+function startsBlockSequence(rest) {
+  for (const line of rest.split("\n")) {
+    if (line.trim() === "" || line.trimStart().startsWith("#"))
+      continue;
+    return BLOCK_SEQUENCE_ENTRY.test(line);
+  }
+  return false;
+}
+function declaresPnpmPackages(dir) {
+  const content = readIfPresent(path5.join(dir, "pnpm-workspace.yaml"));
+  if (content == null)
+    return false;
+  const match = TOP_LEVEL_PACKAGES_KEY.exec(content);
+  if (match == null)
+    return false;
+  const inline = match[1].trim();
+  if (inline.startsWith("["))
+    return !EMPTY_FLOW_SEQUENCE.test(inline);
+  if (inline !== "")
+    return false;
+  return startsBlockSequence(content.slice(match.index + match[0].length));
 }
-function hasWorkspacesField(dir) {
-  const manifest = path5.join(dir, "package.json");
-  if (!existsSync5(manifest))
+function declaresNpmWorkspaces(dir) {
+  const content = readIfPresent(path5.join(dir, "package.json"));
+  if (content == null)
     return false;
+  let workspaces;
   try {
-    const parsed = JSON.parse(readFileSync4(manifest, "utf8"));
-    return parsed.workspaces != null;
+    ({ workspaces } = JSON.parse(content));
   } catch {
     return false;
   }
+  if (Array.isArray(workspaces))
+    return workspaces.length > 0;
+  const packages = workspaces?.packages;
+  return Array.isArray(packages) && packages.length > 0;
+}
+
+// src/detect/layout.ts
+var IGNORED_ENTRIES = /* @__PURE__ */ new Set([".git", ".DS_Store", ".gitignore", ".gitattributes", "LICENSE", "README.md", ".idea", ".vscode"]);
+function isEmptyDir(dir) {
+  if (!existsSync6(dir))
+    return true;
+  return readdirSync4(dir).every((entry) => IGNORED_ENTRIES.has(entry));
 }
 function detectMonorepoTools(dir) {
   const tools = [];
-  if (existsSync5(path5.join(dir, "pnpm-workspace.yaml")))
+  if (declaresPnpmPackages(dir))
     tools.push("pnpm-workspace");
-  if (hasWorkspacesField(dir))
+  if (declaresNpmWorkspaces(dir))
     tools.push("npm-workspaces");
-  if (existsSync5(path5.join(dir, "turbo.json")))
+  if (existsSync6(path6.join(dir, "turbo.json")))
     tools.push("turbo");
-  if (existsSync5(path5.join(dir, "nx.json")))
+  if (existsSync6(path6.join(dir, "nx.json")))
     tools.push("nx");
   return tools;
 }
 function detectWorkspaceDirs(dir) {
-  return ["apps", "packages", "libs", "services"].filter((name) => existsSync5(path5.join(dir, name)) && statSync2(path5.join(dir, name)).isDirectory());
+  return ["apps", "packages", "libs", "services"].filter((name) => existsSync6(path6.join(dir, name)) && statSync2(path6.join(dir, name)).isDirectory());
 }
 function packageName(dir) {
   try {
-    const parsed = JSON.parse(readFileSync4(path5.join(dir, "package.json"), "utf8"));
+    const parsed = JSON.parse(readFileSync5(path6.join(dir, "package.json"), "utf8"));
     return typeof parsed.name === "string" && parsed.name !== "" ? parsed.name : null;
   } catch {
     return null;
   }
 }
 function detectWorkspacePackages(root, workspaceDirs) {
-  return workspaceDirs.flatMap((parent) => readdirSync4(path5.join(root, parent)).sort().map((entry) => `${parent}/${entry}`).filter((dir) => existsSync5(path5.join(root, dir, "package.json"))).map((dir) => ({ dir, name: packageName(path5.join(root, dir)) ?? dir.split("/").at(-1) ?? dir })));
+  return workspaceDirs.flatMap((parent) => readdirSync4(path6.join(root, parent)).sort().map((entry) => `${parent}/${entry}`).filter((dir) => existsSync6(path6.join(root, dir, "package.json"))).map((dir) => ({ dir, name: packageName(path6.join(root, dir)) ?? dir.split("/").at(-1) ?? dir })));
 }
 function detectLayout(dir, monorepoTools, workspaceDirs, hasSrc) {
   if (isEmptyDir(dir))
     return "empty";
   if (monorepoTools.length > 0 || workspaceDirs.length > 0)
     return "monorepo";
-  if (hasSrc || existsSync5(path5.join(dir, "package.json")))
+  if (hasSrc || existsSync6(path6.join(dir, "package.json")))
     return "single";
   return "unknown";
 }
 
 // src/detect/package-manager.ts
 import { execFileSync } from "child_process";
-import { existsSync as existsSync6, readFileSync as readFileSync5 } from "fs";
-import path6 from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
+import path7 from "path";
 var LOCKFILES = [
   ["pnpm-lock.yaml", "pnpm"],
   ["bun.lockb", "bun"],
@@ -381,11 +425,11 @@ var LOCKFILES = [
   ["package-lock.json", "npm"]
 ];
 function fromPackageManagerField(dir) {
-  const manifest = path6.join(dir, "package.json");
-  if (!existsSync6(manifest))
+  const manifest = path7.join(dir, "package.json");
+  if (!existsSync7(manifest))
     return null;
   try {
-    const parsed = JSON.parse(readFileSync5(manifest, "utf8"));
+    const parsed = JSON.parse(readFileSync6(manifest, "utf8"));
     const name = parsed.packageManager?.split("@")[0];
     return name === "pnpm" || name === "npm" || name === "yarn" || name === "bun" ? name : null;
   } catch {
@@ -397,10 +441,10 @@ function detectPackageManager(dir) {
   if (declared != null)
     return declared;
   for (const [lockfile, manager] of LOCKFILES) {
-    if (existsSync6(path6.join(dir, lockfile)))
+    if (existsSync7(path7.join(dir, lockfile)))
       return manager;
   }
-  return existsSync6(path6.join(dir, "package.json")) ? "npm" : "none";
+  return existsSync7(path7.join(dir, "package.json")) ? "npm" : "none";
 }
 var pnpmVersionCache;
 function detectPnpmVersion() {
@@ -416,10 +460,10 @@ function detectPnpmVersion() {
 
 // src/detect/index.ts
 function detect(dir) {
-  const root = path7.resolve(dir);
+  const root = path8.resolve(dir);
   const monorepoTools = detectMonorepoTools(root);
   const workspaceDirs = detectWorkspaceDirs(root);
-  const hasSrc = existsSync7(path7.join(root, "src"));
+  const hasSrc = existsSync8(path8.join(root, "src"));
   return {
     dir: root,
     packageManager: detectPackageManager(root),
@@ -436,14 +480,14 @@ function detect(dir) {
 
 // src/materialize/apply.ts
 import { mkdirSync, writeFileSync as writeFileSync2 } from "fs";
-import path8 from "path";
+import path9 from "path";
 function applyPlan(root, ops) {
   const written = [];
   for (const op of ops) {
     if (op.action === "skip")
       continue;
-    const absolute = path8.join(root, op.target);
-    mkdirSync(path8.dirname(absolute), { recursive: true });
+    const absolute = path9.join(root, op.target);
+    mkdirSync(path9.dirname(absolute), { recursive: true });
     writeFileSync2(absolute, op.content);
     written.push(op);
   }
@@ -451,8 +495,8 @@ function applyPlan(root, ops) {
 }
 
 // src/materialize/plan.ts
-import { existsSync as existsSync9, readFileSync as readFileSync6 } from "fs";
-import path10 from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync7 } from "fs";
+import path11 from "path";
 
 // src/materialize/rules.ts
 var CLAUDE_RULES_DIR = ".claude/rules/";
@@ -614,20 +658,20 @@ ${end}
 }
 
 // src/materialize/templates.ts
-import { existsSync as existsSync8, readdirSync as readdirSync5, statSync as statSync3 } from "fs";
-import path9 from "path";
+import { existsSync as existsSync9, readdirSync as readdirSync5, statSync as statSync3 } from "fs";
+import path10 from "path";
 import { fileURLToPath } from "url";
-var HERE = path9.dirname(fileURLToPath(import.meta.url));
+var HERE = path10.dirname(fileURLToPath(import.meta.url));
 function templatesRoot() {
-  const candidates = [path9.resolve(HERE, "../templates"), path9.resolve(HERE, "../../templates")];
-  const found = candidates.find((candidate) => existsSync8(candidate));
+  const candidates = [path10.resolve(HERE, "../templates"), path10.resolve(HERE, "../../templates")];
+  const found = candidates.find((candidate) => existsSync9(candidate));
   if (found == null)
     throw new Error(`templates directory not found next to ${HERE}`);
   return found;
 }
 var EXISTING_SUFFIX = ".existing.eta";
 function toTargetPath(relative) {
-  const segments = relative.split(path9.sep).map((segment) => segment.startsWith("_") ? `.${segment.slice(1)}` : segment);
+  const segments = relative.split(path10.sep).map((segment) => segment.startsWith("_") ? `.${segment.slice(1)}` : segment);
   const joined = segments.join("/");
   if (joined.endsWith(EXISTING_SUFFIX))
     return { target: joined.slice(0, -EXISTING_SUFFIX.length), rendered: true, variant: "existing" };
@@ -635,22 +679,22 @@ function toTargetPath(relative) {
 }
 function walk(root, current, files) {
   for (const entry of readdirSync5(current).sort()) {
-    const absolute = path9.join(current, entry);
+    const absolute = path10.join(current, entry);
     if (statSync3(absolute).isDirectory())
       walk(root, absolute, files);
     else if (entry !== ".DS_Store")
-      files.push(path9.relative(root, absolute));
+      files.push(path10.relative(root, absolute));
   }
 }
 function listTemplateFiles(group) {
-  const root = path9.join(templatesRoot(), group);
-  if (!existsSync8(root))
+  const root = path10.join(templatesRoot(), group);
+  if (!existsSync9(root))
     throw new Error(`template group "${group}" does not exist`);
   const files = [];
   walk(root, root, files);
   return files.map((relative) => {
     const { target, rendered, variant } = toTargetPath(relative);
-    return { group, source: path9.join(root, relative), target, rendered, variant };
+    return { group, source: path10.join(root, relative), target, rendered, variant };
   });
 }
 var BLOCK = /^[ \t]*\{\{#(if|unless) (\w+)\}\}[ \t]*\n([\s\S]*?)^[ \t]*\{\{\/\1\}\}[ \t]*\n/gm;
@@ -677,7 +721,7 @@ function mountTarget(mount, target) {
   return mount.into == null || mount.into === "." ? target : `${mount.into.replace(/\/$/, "")}/${target}`;
 }
 function readTemplate(source, rendered, vars) {
-  const raw = readFileSync6(source, "utf8");
+  const raw = readFileSync7(source, "utf8");
   return rendered ? render(raw, vars) : raw;
 }
 var SORTED_SECTIONS = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
@@ -735,12 +779,12 @@ function layerJson(earlier, later) {
 var NOT_ADDED_TO_EXISTING_MANIFEST = ["version"];
 function planOne(root, target, content, conflicts, existingVariant) {
   const strategy = strategyFor(target);
-  const absolute = path10.join(root, target);
-  const exists = existsSync9(absolute);
+  const absolute = path11.join(root, target);
+  const exists = existsSync10(absolute);
   if (!exists)
     return { target, strategy, action: "create", content: strategy === "append-block" ? appendBlock("", content, target) : content };
   if (strategy === "merge-json") {
-    const existing = JSON.parse(readFileSync6(absolute, "utf8"));
+    const existing = JSON.parse(readFileSync7(absolute, "utf8"));
     const incoming = JSON.parse(content);
     for (const key of NOT_ADDED_TO_EXISTING_MANIFEST)
       delete incoming[key];
@@ -751,7 +795,7 @@ function planOne(root, target, content, conflicts, existingVariant) {
 ` };
   }
   if (strategy === "append-block") {
-    const existing = readFileSync6(absolute, "utf8");
+    const existing = readFileSync7(absolute, "utf8");
     return { target, strategy, action: "append", content: appendBlock(existing, existingVariant ?? content, target) };
   }
   return { target, strategy, action: "skip", content, note: "exists, review manually" };
@@ -987,14 +1031,14 @@ function createClackPrompter(lore, streams = {}) {
 }
 
 // src/version.ts
-import { readFileSync as readFileSync7 } from "fs";
-import path11 from "path";
+import { readFileSync as readFileSync8 } from "fs";
+import path12 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
-var HERE2 = path11.dirname(fileURLToPath2(import.meta.url));
+var HERE2 = path12.dirname(fileURLToPath2(import.meta.url));
 function readVersion() {
   for (const candidate of ["../package.json", "../../package.json"]) {
     try {
-      const parsed = JSON.parse(readFileSync7(path11.resolve(HERE2, candidate), "utf8"));
+      const parsed = JSON.parse(readFileSync8(path12.resolve(HERE2, candidate), "utf8"));
       if (parsed.name === "mikoshi-construct" && parsed.version != null)
         return parsed.version;
     } catch {
@@ -1094,7 +1138,7 @@ async function askChoices(ui2, options, report, root, prompter) {
   return { presetId, ai, projectName, review };
 }
 async function runInit(ui2, options, prompter) {
-  const root = path12.resolve(options.dir);
+  const root = path13.resolve(options.dir);
   mkdirSync2(root, { recursive: true });
   if (!options.yes && prompter == null) {
     ui2.glitch(ui2.lore.needsTerminal);
@@ -1462,7 +1506,7 @@ var cost = defineCommand({
     json: { type: "boolean", description: "Machine-readable report", default: false }
   },
   run({ args }) {
-    const runs = collectWorkflowRuns(path13.resolve(args.dir));
+    const runs = collectWorkflowRuns(path14.resolve(args.dir));
     if (args.json) {
       const selected = runs == null ? null : args.last ? runs.slice(-1) : runs;
       process4.stdout.write(`${JSON.stringify(selected, null, 2)}

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "mikoshi-construct",
   "type": "module",
-  "version": "0.1.1",
-  "packageManager": "pnpm@12.4.2",
+  "version": "0.1.3",
   "description": "Bootstrap for AI-native software projects. Start with a proven engineering workflow instead of an empty repository.",
   "author": "Eli Tabrisov",
   "license": "MIT",
@@ -36,23 +35,6 @@
   "engines": {
     "node": ">=20"
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsx src/cli.ts",
-    "lint": "eslint .",
-    "lint:fix": "eslint --fix .",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "quality": "pnpm composition:check && pnpm lint && pnpm typecheck && pnpm test",
-    "prepublishOnly": "pnpm build",
-    "composition:render": "tsx scripts/composition/sync-docs.ts",
-    "composition:check": "tsx scripts/composition/check.ts",
-    "ci": "pnpm run quality",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "pnpm build && npm publish --provenance --access public"
-  },
   "dependencies": {
     "@clack/prompts": "^1.8.0",
     "citty": "^0.2.2",
@@ -69,5 +51,21 @@
     "typescript": "^5.9.3",
     "vitest": "^5.0.0",
     "yaml": "^2.9.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "quality": "pnpm composition:check && pnpm lint && pnpm typecheck && pnpm test",
+    "composition:render": "tsx scripts/composition/sync-docs.ts",
+    "composition:check": "tsx scripts/composition/check.ts",
+    "ci": "pnpm run quality",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm build && changeset publish"
   }
-}
+}