@auis/cli 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,14 +1,14 @@
1
1
  # @auis/cli
2
2
 
3
- The CLI for [**Auis**](https://github.com/gregoriombp/AuisDesign) — a code-native
3
+ Scaffold [**Auis**](https://github.com/gregoriombp/AuisDesign) — a code-native
4
4
  design builder. One command, no clone, no config:
5
5
 
6
6
  ```bash
7
- npx @auis/cli my-product
7
+ npx @auis/cli@latest my-product
8
8
  ```
9
9
 
10
10
  ```
11
- auis 0.1.0
11
+ auis 0.2.0
12
12
  code-native design builder
13
13
 
14
14
  ✓ Template main · tarball
@@ -39,12 +39,13 @@ codebase, and AI agents build against them under enforced rules:
39
39
  - **State Mode** (`/auis/states`) — every registered screen in every state, side by side.
40
40
  - **37 agent skills** — execution contracts for Claude Code, Codex and Cursor.
41
41
 
42
- ## Usage
42
+ ## Options
43
43
 
44
44
  ```
45
- npx @auis/cli [directory] [options]
46
- npx @auis/cli new [directory] [options] same thing
45
+ npx @auis/cli@latest [directory] [options] scaffold a new project
46
+ npx @auis/cli@latest doctor [directory] read an existing repo, write nothing
47
47
 
48
+ --json doctor only: the full report as JSON
48
49
  -r, --ref <ref> branch, tag or commit of the template (default: main)
49
50
  --pm <manager> npm | pnpm | yarn | bun (default: detected)
50
51
  --no-install skip dependency installation
@@ -58,10 +59,11 @@ npx @auis/cli new [directory] [options] same thing
58
59
  Examples:
59
60
 
60
61
  ```bash
61
- npx @auis/cli my-product # new directory
62
- npx @auis/cli . # current directory
63
- npx @auis/cli my-product --pm pnpm --no-git
64
- npx @auis/cli my-product --ref v1.0.0
62
+ npx @auis/cli@latest my-product # new directory
63
+ npx @auis/cli@latest . # current directory
64
+ npx @auis/cli@latest my-product --pm pnpm --no-git
65
+ npx @auis/cli@latest my-product --ref v1.0.0
66
+ npx @auis/cli@latest doctor # what Auis can do in the current repo, writes nothing
65
67
  ```
66
68
 
67
69
  Requires **Node.js ≥ 20**. The template is fetched as a GitHub tarball (`tar`),
@@ -71,8 +73,8 @@ falling back to `git clone --depth 1`. The CLI itself has zero dependencies.
71
73
 
72
74
  Everything in the repository, minus the parts that only concern contributing to
73
75
  Auis (`.github/ISSUE_TEMPLATE`, `PULL_REQUEST_TEMPLATE.md`, `CONTRIBUTING.md`,
74
- `CODE_OF_CONDUCT.md`, the extraction/cleanup notes, and the `packages/`
75
- directory this CLI lives in), plus:
76
+ `CODE_OF_CONDUCT.md`, the extraction/cleanup notes, and this `packages/`
77
+ directory), plus:
76
78
 
77
79
  - `package.json` renamed to your project, `0.1.0`, `private: true`, with an
78
80
  `auis` field recording the template ref it came from;
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@auis/cli",
3
- "version": "0.1.0",
4
- "description": "The Auis CLI — scaffold a code-native design builder: Next.js + Tailwind + shadcn/ui, with agent skills built in.",
3
+ "version": "0.2.0",
4
+ "description": "Scaffold Auis — the code-native design builder for Next.js + Tailwind + shadcn/ui, with agent skills built in.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "auis": "bin/auis.mjs"
@@ -18,9 +18,6 @@
18
18
  "engines": {
19
19
  "node": ">=20"
20
20
  },
21
- "publishConfig": {
22
- "access": "public"
23
- },
24
21
  "scripts": {
25
22
  "test": "node --test test/*.test.mjs"
26
23
  },
@@ -29,6 +26,7 @@
29
26
  "design-system",
30
27
  "design-builder",
31
28
  "scaffold",
29
+ "create",
32
30
  "starter",
33
31
  "nextjs",
34
32
  "shadcn-ui",
@@ -43,7 +41,7 @@
43
41
  "repository": {
44
42
  "type": "git",
45
43
  "url": "git+https://github.com/gregoriombp/AuisDesign.git",
46
- "directory": "packages/cli"
44
+ "directory": "packages/auis"
47
45
  },
48
46
  "homepage": "https://github.com/gregoriombp/AuisDesign#readme",
49
47
  "bugs": {
package/src/cli.mjs CHANGED
@@ -1,18 +1,23 @@
1
1
  /**
2
- * Argument parsing and dispatch for the Auis CLI.
2
+ * Argument parsing and dispatch for `npx @auis/cli`.
3
3
  *
4
- * `new` is the default command, so the bare form reads as the install line it
5
- * is: `npx @auis/cli my-product`. Commands are dispatched by name to leave room
6
- * for the ones that come next without changing how people invoke the CLI.
4
+ * `create` stays the default, so the bare form reads as the install line it is:
5
+ * `npx @auis/cli@latest my-product`. `doctor` is the other half — it reads an
6
+ * existing repository and reports what Auis could and could not do inside it,
7
+ * without writing anything.
7
8
  */
8
9
 
9
10
  import fs from "node:fs";
10
11
  import { color, banner, fail, write } from "./ui.mjs";
11
12
  import { DEFAULT_REF, REPO_URL } from "./template.mjs";
12
13
  import { PACKAGE_MANAGERS, create } from "./create.mjs";
14
+ import { doctor } from "./doctor.mjs";
15
+
16
+ // Re-exported for the create-auis alias, which imports the package root.
17
+ export { restoreCursorOnExit } from "./ui.mjs";
13
18
 
14
19
  const MIN_NODE_MAJOR = 20;
15
- const COMMANDS = new Set(["new", "create", "init"]);
20
+ const CREATE_ALIASES = new Set(["create", "init", "new"]);
16
21
 
17
22
  export const version = JSON.parse(
18
23
  fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"),
@@ -20,7 +25,9 @@ export const version = JSON.parse(
20
25
 
21
26
  export function parseArgs(argv) {
22
27
  const options = {
28
+ command: "create",
23
29
  directory: undefined,
30
+ json: false,
24
31
  ref: DEFAULT_REF,
25
32
  packageManager: undefined,
26
33
  install: true,
@@ -31,10 +38,14 @@ export function parseArgs(argv) {
31
38
  version: false,
32
39
  };
33
40
 
34
- // `auis my-app`, `auis new my-app`, `auis create my-app` and `auis init my-app`
35
- // are the same call: scaffolding is the default command.
41
+ // `auis my-app`, `auis create my-app` and `auis new my-app` are the same call.
36
42
  const rest = [...argv];
37
- if (COMMANDS.has(rest[0])) rest.shift();
43
+ if (rest[0] === "doctor") {
44
+ options.command = "doctor";
45
+ rest.shift();
46
+ } else if (CREATE_ALIASES.has(rest[0])) {
47
+ rest.shift();
48
+ }
38
49
 
39
50
  while (rest.length > 0) {
40
51
  const arg = rest.shift();
@@ -55,6 +66,9 @@ export function parseArgs(argv) {
55
66
  case "--force":
56
67
  options.force = true;
57
68
  break;
69
+ case "--json":
70
+ options.json = true;
71
+ break;
58
72
  case "--no-install":
59
73
  case "--skip-install":
60
74
  options.install = false;
@@ -103,13 +117,14 @@ export function parseArgs(argv) {
103
117
  export function help() {
104
118
  const c = color;
105
119
  write();
106
- write(` ${c.bold("auis")} — scaffold a code-native design builder`);
120
+ write(` ${c.bold("auis")} — a code-native design builder`);
107
121
  write();
108
122
  write(` ${c.bold("Usage")}`);
109
- write(` npx @auis/cli ${c.dim("[directory] [options]")}`);
110
- write(` npx @auis/cli new ${c.dim("[directory] [options]")} ${c.dim("(same thing)")}`);
123
+ write(` npx @auis/cli@latest ${c.dim("[directory] [options]")} ${c.dim("scaffold a new project")}`);
124
+ write(` npx @auis/cli@latest doctor ${c.dim("[directory]")} ${c.dim("read an existing repo, write nothing")}`);
111
125
  write();
112
126
  write(` ${c.bold("Options")}`);
127
+ write(` --json doctor only: the full report as JSON`);
113
128
  write(` -r, --ref ${c.dim("<ref>")} branch, tag or commit of the template ${c.dim(`(default: ${DEFAULT_REF})`)}`);
114
129
  write(` --pm ${c.dim("<manager>")} ${PACKAGE_MANAGERS.join(" | ")} ${c.dim("(default: detected)")}`);
115
130
  write(` --no-install skip dependency installation`);
@@ -120,9 +135,9 @@ export function help() {
120
135
  write(` -v, --version print the CLI version`);
121
136
  write();
122
137
  write(` ${c.bold("Examples")}`);
123
- write(` npx @auis/cli my-product`);
124
- write(` npx @auis/cli . --no-install`);
125
- write(` npx @auis/cli my-product --pm pnpm --ref v1.0.0`);
138
+ write(` npx @auis/cli@latest my-product`);
139
+ write(` npx @auis/cli@latest . --no-install`);
140
+ write(` npx @auis/cli@latest doctor`);
126
141
  write();
127
142
  write(` ${c.dim(REPO_URL)}`);
128
143
  write();
@@ -152,6 +167,12 @@ export async function run(argv = []) {
152
167
  return 0;
153
168
  }
154
169
 
170
+ if (options.command === "doctor") {
171
+ // The JSON form is somebody's stdin — keep the banner out of it.
172
+ if (!options.json) banner(version);
173
+ return doctor({ directory: options.directory ?? ".", json: options.json, cliVersion: version });
174
+ }
175
+
155
176
  banner(version);
156
177
  return create({ ...options, cliVersion: version });
157
178
  }
package/src/create.mjs CHANGED
@@ -1,6 +1,5 @@
1
1
  /**
2
- * `auis [directory]` — the `new` command: scaffold a project from the Auis
3
- * template.
2
+ * `auis [directory]` — scaffold a project from the Auis template.
4
3
  *
5
4
  * The template is the AuisDesign repository itself: it is not a library you
6
5
  * install into an app, it *is* the app (Next.js + Tailwind v4 + shadcn/ui plus
@@ -90,7 +89,7 @@ async function personalize(root, { name, ref, cliVersion }) {
90
89
  next.version = "0.1.0";
91
90
  next.description = `${name} — a design system and product surface built with Auis.`;
92
91
  next.private = true;
93
- next.auis = { template: `${REPO_URL}#${ref}`, createdWith: `@auis/cli@${cliVersion}` };
92
+ next.auis = { template: `${REPO_URL}#${ref}`, createdWith: `auis@${cliVersion}` };
94
93
 
95
94
  await fs.writeFile(pkgPath, `${JSON.stringify(next, null, 2)}\n`);
96
95
 
package/src/detect.mjs ADDED
@@ -0,0 +1,368 @@
1
+ /**
2
+ * Read-only inspection of a repository that is not Auis's.
3
+ *
4
+ * Every function here only reads. Nothing in this module creates, moves or
5
+ * deletes a file — `auis doctor` is the instrument people run BEFORE they trust
6
+ * us with their repository, so it has to be safe to run on anything.
7
+ *
8
+ * Each detection carries `evidence`: the file and the thing inside it that
9
+ * decided the answer. A verdict nobody can argue with is a verdict nobody can
10
+ * correct, and these are guesses about someone else's codebase.
11
+ */
12
+
13
+ import fs from "node:fs";
14
+ import path from "node:path";
15
+
16
+ /** Directories that never hold host source, and are big enough to matter. */
17
+ const SKIP_DIRS = new Set([
18
+ ".git", "node_modules", ".next", ".nuxt", ".svelte-kit", ".turbo", ".cache",
19
+ "dist", "build", "out", "coverage", "vendor", "__pycache__",
20
+ ]);
21
+
22
+ const SOURCE_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".vue", ".svelte", ".astro"]);
23
+
24
+ function read(root, rel) {
25
+ try {
26
+ return fs.readFileSync(path.join(root, rel), "utf8");
27
+ } catch {
28
+ return null;
29
+ }
30
+ }
31
+
32
+ function readJson(root, rel) {
33
+ const raw = read(root, rel);
34
+ if (raw === null) return null;
35
+ try {
36
+ // tsconfig.json is JSONC in practice: strip comments and trailing commas.
37
+ return JSON.parse(raw.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|\s)\/\/.*$/gm, "$1").replace(/,(\s*[}\]])/g, "$1"));
38
+ } catch {
39
+ return null;
40
+ }
41
+ }
42
+
43
+ const exists = (root, rel) => fs.existsSync(path.join(root, rel));
44
+
45
+ /** Every source file under `root`, capped so a monorepo cannot hang the CLI. */
46
+ export function sourceFiles(root, limit = 4000) {
47
+ const out = [];
48
+ const walk = (dir) => {
49
+ if (out.length >= limit) return;
50
+ let entries;
51
+ try {
52
+ entries = fs.readdirSync(dir, { withFileTypes: true });
53
+ } catch {
54
+ return;
55
+ }
56
+ for (const entry of entries) {
57
+ if (out.length >= limit) return;
58
+ if (entry.name.startsWith(".") && entry.name !== ".claude") continue;
59
+ const p = path.join(dir, entry.name);
60
+ if (entry.isDirectory()) {
61
+ if (!SKIP_DIRS.has(entry.name)) walk(p);
62
+ } else if (SOURCE_EXT.has(path.extname(entry.name))) {
63
+ out.push(p);
64
+ }
65
+ }
66
+ };
67
+ walk(root);
68
+ return out;
69
+ }
70
+
71
+ /** First dependency in `names` that the manifest declares, with its range. */
72
+ function dependency(pkg, names) {
73
+ const all = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}), ...(pkg?.peerDependencies ?? {}) };
74
+ for (const name of names) {
75
+ if (all[name]) return { name, range: all[name] };
76
+ }
77
+ return null;
78
+ }
79
+
80
+ /** Leading integer of a semver range — good enough to branch on a major. */
81
+ function major(range) {
82
+ const m = String(range ?? "").match(/(\d+)/);
83
+ return m ? Number(m[1]) : null;
84
+ }
85
+
86
+ const FRAMEWORKS = [
87
+ ["next", ["next"]],
88
+ ["nuxt", ["nuxt"]],
89
+ ["remix", ["@remix-run/react", "@remix-run/node"]],
90
+ ["astro", ["astro"]],
91
+ ["sveltekit", ["@sveltejs/kit"]],
92
+ ["angular", ["@angular/core"]],
93
+ ["vite", ["vite"]],
94
+ ["cra", ["react-scripts"]],
95
+ ];
96
+
97
+ function detectFramework(root, pkg) {
98
+ for (const [name, deps] of FRAMEWORKS) {
99
+ const hit = dependency(pkg, deps);
100
+ if (hit) {
101
+ return {
102
+ name,
103
+ version: hit.range,
104
+ major: major(hit.range),
105
+ confidence: "certain",
106
+ evidence: [`package.json#${hit.name}`],
107
+ };
108
+ }
109
+ }
110
+ return { name: "unknown", version: null, major: null, confidence: "certain", evidence: ["package.json"] };
111
+ }
112
+
113
+ function detectRouter(root, framework) {
114
+ if (framework.name === "next") {
115
+ for (const base of ["app", "src/app"]) {
116
+ if (exists(root, `${base}/layout.tsx`) || exists(root, `${base}/layout.jsx`)) {
117
+ return { name: "app-router", evidence: [`${base}/layout.tsx`] };
118
+ }
119
+ }
120
+ for (const base of ["pages", "src/pages"]) {
121
+ if (exists(root, base)) return { name: "pages-router", evidence: [base] };
122
+ }
123
+ return { name: "unknown", evidence: [] };
124
+ }
125
+ return { name: framework.name === "unknown" ? "unknown" : "other", evidence: [] };
126
+ }
127
+
128
+ function detectRootLayout(root, router) {
129
+ if (router.name !== "app-router") return { path: null, patchable: false, evidence: [] };
130
+ for (const base of ["app", "src/app"]) {
131
+ for (const ext of ["tsx", "jsx"]) {
132
+ const rel = `${base}/layout.${ext}`;
133
+ const src = read(root, rel);
134
+ if (src === null) continue;
135
+ // One <body> means one unambiguous place to mount. Anything else is the
136
+ // user's call, not ours — `init` prints the two lines instead of guessing.
137
+ const bodies = (src.match(/<body[\s>]/g) ?? []).length;
138
+ return { path: rel, patchable: bodies === 1, bodies, evidence: [rel] };
139
+ }
140
+ }
141
+ return { path: null, patchable: false, evidence: [] };
142
+ }
143
+
144
+ const CSS_LIBS = [
145
+ ["styled-components", ["styled-components"]],
146
+ ["emotion", ["@emotion/react", "@emotion/styled"]],
147
+ ["stitches", ["@stitches/react"]],
148
+ ["vanilla-extract", ["@vanilla-extract/css"]],
149
+ ["bootstrap", ["bootstrap"]],
150
+ ["bulma", ["bulma"]],
151
+ ];
152
+
153
+ function detectCss(root, pkg, files) {
154
+ const tailwind = dependency(pkg, ["tailwindcss"]);
155
+ if (tailwind) {
156
+ // v4 is `@import "tailwindcss"` in the stylesheet; v3 is a tailwind.config.*
157
+ const v4Config = ["tailwind.config.js", "tailwind.config.ts", "tailwind.config.mjs", "tailwind.config.cjs"]
158
+ .some((f) => exists(root, f));
159
+ return {
160
+ solution: "tailwind",
161
+ major: major(tailwind.range),
162
+ evidence: [`package.json#tailwindcss`, v4Config ? "tailwind.config.*" : "no tailwind.config.*"],
163
+ };
164
+ }
165
+ for (const [name, deps] of CSS_LIBS) {
166
+ const hit = dependency(pkg, deps);
167
+ if (hit) return { solution: name, major: major(hit.range), evidence: [`package.json#${hit.name}`] };
168
+ }
169
+ const modules = files.filter((f) => f.endsWith(".module.css")).length;
170
+ if (modules > 0) return { solution: "css-modules", major: null, evidence: [`${modules} *.module.css`] };
171
+ return { solution: "plain-css", major: null, evidence: [] };
172
+ }
173
+
174
+ /** The stylesheet the app imports first — where tokens and resets would live. */
175
+ function findCssEntry(root) {
176
+ const candidates = [
177
+ "app/globals.css", "src/app/globals.css", "src/index.css", "src/main.css",
178
+ "src/styles/globals.css", "styles/globals.css", "app/app.css", "src/styles.css",
179
+ ];
180
+ return candidates.find((rel) => exists(root, rel)) ?? null;
181
+ }
182
+
183
+ function detectTokens(root, cssEntry) {
184
+ if (!cssEntry) return { customProperties: 0, prefixes: {}, evidence: [] };
185
+ const css = read(root, cssEntry) ?? "";
186
+ // Declarations only (`--x: value`), never `var(--x)` references.
187
+ const declared = [...css.matchAll(/(^|[;{\s])(--[A-Za-z0-9_-]+)\s*:/g)].map((m) => m[2]);
188
+ const unique = [...new Set(declared)];
189
+ const prefixes = {};
190
+ for (const name of unique) {
191
+ const key = name.split("-").slice(0, 3).join("-").replace(/[0-9]+$/, "");
192
+ prefixes[key] = (prefixes[key] ?? 0) + 1;
193
+ }
194
+ return { customProperties: unique.length, prefixes, evidence: [cssEntry] };
195
+ }
196
+
197
+ /** How hard the host's own stylesheet fights back at anything we render. */
198
+ function detectReset(root, cssEntry, css) {
199
+ const signals = [];
200
+ if (css.includes('@import "tailwindcss"') || css.includes("@import 'tailwindcss'")) signals.push("tailwind preflight");
201
+ if (/@tailwind\s+base/.test(css)) signals.push("tailwind base");
202
+ if (/normalize\.css|sanitize\.css/.test(css)) signals.push("normalize/sanitize");
203
+ const bangs = (css.match(/!important/g) ?? []).length;
204
+ if (bangs > 20) signals.push(`${bangs} !important`);
205
+ if (/^\s*(button|input|a|h1|body)\s*\{/m.test(css)) signals.push("bare element rules");
206
+ const level = signals.length >= 2 ? "high" : signals.length === 1 ? "medium" : "low";
207
+ return { level, signals, evidence: cssEntry ? [cssEntry] : [] };
208
+ }
209
+
210
+ const ICON_LIBS = [
211
+ ["material-symbols", ["@material-symbols/svg-400", "material-symbols"]],
212
+ ["lucide", ["lucide-react", "lucide"]],
213
+ ["heroicons", ["@heroicons/react"]],
214
+ ["react-icons", ["react-icons"]],
215
+ ["phosphor", ["@phosphor-icons/react"]],
216
+ ["tabler", ["@tabler/icons-react"]],
217
+ ];
218
+
219
+ function detectIcons(root, pkg, files) {
220
+ for (const [name, deps] of ICON_LIBS) {
221
+ const hit = dependency(pkg, deps);
222
+ if (hit) return { system: name, confidence: "certain", evidence: [`package.json#${hit.name}`] };
223
+ }
224
+ // Material Symbols is usually a Google Fonts <link>, not a dependency.
225
+ for (const file of files.slice(0, 400)) {
226
+ let src;
227
+ try {
228
+ src = fs.readFileSync(file, "utf8");
229
+ } catch {
230
+ continue;
231
+ }
232
+ if (src.includes("Material+Symbols")) {
233
+ return { system: "material-symbols", confidence: "likely", evidence: [path.relative(root, file)] };
234
+ }
235
+ }
236
+ return { system: "none", confidence: "likely", evidence: [] };
237
+ }
238
+
239
+ function detectAlias(root) {
240
+ for (const rel of ["tsconfig.json", "jsconfig.json"]) {
241
+ const cfg = readJson(root, rel);
242
+ const paths = cfg?.compilerOptions?.paths;
243
+ if (paths) {
244
+ const entry = Object.keys(paths)[0];
245
+ return { style: entry, evidence: [`${rel}#compilerOptions.paths`] };
246
+ }
247
+ }
248
+ return { style: null, evidence: [] };
249
+ }
250
+
251
+ /**
252
+ * Is this path ignored — by a rule naming it, or by one naming a directory
253
+ * above it? `/.agents/` covers `.agents/skills`, and the difference decides how
254
+ * bad a wrong delete would be, so the ancestors have to be checked too.
255
+ *
256
+ * Literal paths only. A glob rule reads as "not ignored", which errs toward
257
+ * warning the user rather than reassuring them wrongly.
258
+ */
259
+ export function isIgnored(gitignore, rel) {
260
+ const rules = gitignore
261
+ .split("\n")
262
+ .map((line) => line.trim())
263
+ .filter((line) => line && !line.startsWith("#") && !line.includes("*"))
264
+ .map((line) => line.replace(/^\//, "").replace(/\/$/, ""));
265
+ const parts = rel.split("/");
266
+ for (let i = parts.length; i > 0; i--) {
267
+ if (rules.includes(parts.slice(0, i).join("/"))) return true;
268
+ }
269
+ return false;
270
+ }
271
+
272
+ /** Everything Auis might want to write that the host may already own. */
273
+ export function detectAgentFiles(root) {
274
+ const gitignore = read(root, ".gitignore") ?? "";
275
+ const ignored = (rel) => isIgnored(gitignore, rel);
276
+ const out = [];
277
+ for (const rel of ["AGENTS.md", "CLAUDE.md", ".mcp.json", "components.json"]) {
278
+ if (exists(root, rel)) out.push({ path: rel, kind: "file", gitignored: ignored(rel) });
279
+ }
280
+ for (const rel of [".claude/skills", ".agents/skills", ".cursor/rules"]) {
281
+ if (!exists(root, rel)) continue;
282
+ let entries = [];
283
+ try {
284
+ entries = fs.readdirSync(path.join(root, rel)).filter((e) => !e.startsWith("."));
285
+ } catch {
286
+ /* unreadable is the same as empty for our purposes */
287
+ }
288
+ out.push({ path: rel, kind: "dir", entries: entries.length, names: entries, gitignored: ignored(rel) });
289
+ }
290
+ return out;
291
+ }
292
+
293
+ function detectRepo(root) {
294
+ const git = exists(root, ".git");
295
+ return { vcs: git ? "git" : null, evidence: git ? [".git"] : [] };
296
+ }
297
+
298
+ /** Host web components: our anchors cannot reach inside a closed shadow root. */
299
+ function detectWebComponents(root, files) {
300
+ for (const file of files) {
301
+ let src;
302
+ try {
303
+ src = fs.readFileSync(file, "utf8");
304
+ } catch {
305
+ continue;
306
+ }
307
+ if (src.includes("attachShadow(")) {
308
+ return { present: true, evidence: [path.relative(root, file)] };
309
+ }
310
+ }
311
+ return { present: false, evidence: [] };
312
+ }
313
+
314
+ function detectPackageManager(root) {
315
+ const locks = [
316
+ ["pnpm", "pnpm-lock.yaml"], ["yarn", "yarn.lock"],
317
+ ["bun", "bun.lockb"], ["npm", "package-lock.json"],
318
+ ];
319
+ for (const [name, lock] of locks) {
320
+ if (exists(root, lock)) return { name, evidence: [lock] };
321
+ }
322
+ return { name: "npm", evidence: [] };
323
+ }
324
+
325
+ /**
326
+ * Can this project's dev server write files? The bridges persist comments to
327
+ * JSON on disk, so this is what separates a shared queue from a browser-local one.
328
+ */
329
+ function detectDevServer(root, pkg, framework, router) {
330
+ const script = pkg?.scripts?.dev ?? pkg?.scripts?.start ?? null;
331
+ const serverSide =
332
+ (framework.name === "next" && router.name === "app-router") ||
333
+ ["vite", "remix", "nuxt", "sveltekit", "astro"].includes(framework.name);
334
+ return {
335
+ fileWriting: Boolean(script) && serverSide,
336
+ command: script,
337
+ evidence: script ? ["package.json#scripts.dev"] : [],
338
+ };
339
+ }
340
+
341
+ /** Everything `auis doctor` knows about a repository. Reads only. */
342
+ export function detect(root) {
343
+ const pkg = readJson(root, "package.json");
344
+ const files = sourceFiles(root);
345
+ const framework = detectFramework(root, pkg);
346
+ const router = detectRouter(root, framework);
347
+ const cssEntry = findCssEntry(root);
348
+ const cssSource = cssEntry ? (read(root, cssEntry) ?? "") : "";
349
+ const react = dependency(pkg, ["react"]);
350
+
351
+ return {
352
+ name: pkg?.name ?? path.basename(root),
353
+ packageManager: detectPackageManager(root),
354
+ framework,
355
+ react: { version: react?.range ?? null, major: react ? major(react.range) : null, evidence: react ? ["package.json#react"] : [] },
356
+ router,
357
+ rootLayout: detectRootLayout(root, router),
358
+ devServer: detectDevServer(root, pkg, framework, router),
359
+ css: { ...detectCss(root, pkg, files), entry: cssEntry },
360
+ reset: detectReset(root, cssEntry, cssSource),
361
+ tokens: detectTokens(root, cssEntry),
362
+ icons: detectIcons(root, pkg, files),
363
+ alias: detectAlias(root),
364
+ webComponents: detectWebComponents(root, files),
365
+ repo: detectRepo(root),
366
+ sourceFileCount: files.length,
367
+ };
368
+ }
package/src/doctor.mjs ADDED
@@ -0,0 +1,275 @@
1
+ /**
2
+ * `auis doctor` — what Auis can and cannot do in THIS repository.
3
+ *
4
+ * It reads. It never writes, never installs, never asks. And it exits 0 even
5
+ * when every capability comes back unsupported: a non-zero exit teaches people
6
+ * to stop running the one command whose whole job is to tell them the truth
7
+ * before they let us near their code. Exit 1 is reserved for "I could not read
8
+ * the repository at all".
9
+ *
10
+ * Every verdict carries a `because`, and anything less than `supported` carries
11
+ * a `remedy` — the honest alternative, or the thing the host would have to
12
+ * provide. "May not work" is not a verdict.
13
+ */
14
+
15
+ import fs from "node:fs";
16
+ import path from "node:path";
17
+ import { color, write } from "./ui.mjs";
18
+ import { detect, detectAgentFiles } from "./detect.mjs";
19
+
20
+ export const DOCTOR_VERSION = 1;
21
+
22
+ const supported = (id, because) => ({ id, verdict: "supported", because });
23
+ const degraded = (id, because, remedy) => ({ id, verdict: "degraded", because, remedy });
24
+ const unsupported = (id, because, remedy) => ({ id, verdict: "unsupported", because, remedy });
25
+
26
+ /**
27
+ * Capability verdicts, derived from the detections.
28
+ *
29
+ * A capability is something a person would notice losing — not a module. The
30
+ * three registries Edit Mode leans on (variant, typography, style tokens) are
31
+ * keyed to Auis's own class names and its own palette, so in a host they are
32
+ * unsupported until the host supplies a map. That is a verdict, not a bug.
33
+ */
34
+ export function capabilities(d) {
35
+ const out = [];
36
+ const reactOk = d.react.major !== null && d.react.major >= 18;
37
+ const serverBacked = d.devServer.fileWriting;
38
+
39
+ // --- Review -------------------------------------------------------------
40
+ if (reactOk) {
41
+ out.push(supported("review.pins", "Pins anchor through plain DOM — no markup, no wrapper, no provider in your components."));
42
+ out.push(supported("review.draw", "Freehand marks use the same DOM anchoring as pins."));
43
+ } else {
44
+ const why = d.react.major === null
45
+ ? "No React dependency found; the builder chrome is a React tree today."
46
+ : `React ${d.react.major} is below the 18 the chrome needs.`;
47
+ out.push(unsupported("review.pins", why, "A framework-agnostic mount that carries its own React is planned; it does not exist yet."));
48
+ out.push(unsupported("review.draw", why, "Same mount work as review.pins."));
49
+ }
50
+
51
+ if (d.webComponents.present) {
52
+ out.push(degraded(
53
+ "review.anchoring",
54
+ `This app calls attachShadow (${d.webComponents.evidence[0]}); anchors cannot resolve inside a shadow root.`,
55
+ "Pins on those regions fall back to absolute document coordinates and drift when the layout changes."
56
+ ));
57
+ } else {
58
+ out.push(supported("review.anchoring", "No shadow roots in your source — a structural selector plus a text fingerprint can address every element."));
59
+ }
60
+
61
+ if (serverBacked) {
62
+ out.push(supported("review.persistence", `${d.devServer.command} runs a server that can write files, so comments land in a shared queue.`));
63
+ out.push(supported("review.mentions", "Agent mentions need the same server-backed queue, which you have."));
64
+ out.push(supported("skills.bridges", "The bridge skills talk to that queue over HTTP while the dev server is up."));
65
+ } else {
66
+ const why = d.framework.name === "unknown"
67
+ ? "No JavaScript framework detected, so there is no dev server for Auis to mount routes on."
68
+ : `${d.framework.name}${d.router.name === "pages-router" ? " on the Pages Router" : ""} gives Auis no file-writing route to persist through.`;
69
+ out.push(degraded("review.persistence", why, "Comments live in each reviewer's browser; Export/Import moves them. Run `npx @auis/server` for a shared queue."));
70
+ out.push(degraded("review.mentions", why, "Mentions are recorded locally but no agent can read the queue until a server backs it."));
71
+ out.push(unsupported("skills.bridges", why, "The bridge skills read a queue over HTTP; without one they have nothing to read."));
72
+ }
73
+
74
+ // --- Edit ---------------------------------------------------------------
75
+ out.push(supported("edit.text", "Text edits are contenteditable on the live DOM — they work regardless of stack."));
76
+ out.push(supported("edit.reorder", "Reordering moves DOM siblings; no knowledge of your components is needed."));
77
+
78
+ const props = d.tokens.customProperties;
79
+ if (props >= 12) {
80
+ out.push(supported("edit.style", `${props} CSS custom properties declared in ${d.css.entry} — the style picker offers yours.`));
81
+ } else if (props > 0) {
82
+ out.push(degraded("edit.style", `Only ${props} custom properties in ${d.css.entry ?? "your stylesheet"}.`, "The picker offers raw values instead of tokens, so edits will not be token-safe."));
83
+ } else {
84
+ out.push(unsupported("edit.style", "No CSS custom properties found, so there is no token vocabulary to offer.", "Declare tokens on :root, or edit text and layout only."));
85
+ }
86
+
87
+ out.push(unsupported(
88
+ "edit.variant",
89
+ "Variant swapping recognises components by Auis's own class names (au-btn, au-card); yours are different.",
90
+ "Supply a variant map in auis.config so Auis can name your components. Auis will not guess them."
91
+ ));
92
+ out.push(unsupported(
93
+ "edit.typography",
94
+ "Type swapping uses Auis's own utility names (body-sm, display-lg), which this app does not define.",
95
+ "Same variant map as edit.variant."
96
+ ));
97
+
98
+ if (d.icons.system === "material-symbols") {
99
+ out.push(supported("edit.icon", "This app already loads Material Symbols, the ligature set the icon picker writes."));
100
+ } else {
101
+ out.push(unsupported(
102
+ "edit.icon",
103
+ d.icons.system === "none"
104
+ ? "No icon system detected; the picker writes Material Symbols ligature names into your DOM."
105
+ : `This app uses ${d.icons.system}; the picker writes Material Symbols ligature names, which would render as text.`,
106
+ "Edit other properties; icon swapping needs an icon adapter Auis does not have yet."
107
+ ));
108
+ }
109
+
110
+ if (d.framework.name === "next" && d.router.name === "app-router") {
111
+ out.push(supported("edit.materialize", "Routes map to app/<route>/page.tsx, so an agent can find the source behind an edit."));
112
+ } else {
113
+ out.push(unsupported(
114
+ "edit.materialize",
115
+ `Turning an edit into a code change infers the source file from the route, which only holds for the Next App Router (found: ${d.router.name}).`,
116
+ "Edits are still recorded and exportable as JSON — a precise spec a person or an agent can apply by hand."
117
+ ));
118
+ }
119
+
120
+ // --- Flows, states, rulebook -------------------------------------------
121
+ out.push(supported("flow.driver", "Deep links replay clicks by visible text or selector, which needs nothing from your stack."));
122
+ out.push(degraded(
123
+ "states.mode",
124
+ "State Mode needs a hand-written registry of your screens and a hook call inside each page.",
125
+ "Expect to write those entries yourself; nothing about it is automatic."
126
+ ));
127
+ out.push(supported("skills.rulebook", "The skills and conventions are plain files with no runtime — they work in any repository."));
128
+
129
+ return out;
130
+ }
131
+
132
+ /** Paths Auis may want, that the host may already own. */
133
+ export function collisions(root) {
134
+ const out = [];
135
+ for (const entry of detectAgentFiles(root)) {
136
+ const tracked = entry.gitignored ? "gitignored" : "tracked";
137
+ if (entry.path === "AGENTS.md" || entry.path === "CLAUDE.md") {
138
+ out.push({
139
+ path: entry.path, exists: true, gitignored: entry.gitignored, plan: "append-block",
140
+ note: `exists, ${tracked} — auis appends a delimited block and never rewrites what is above it`,
141
+ });
142
+ } else if (entry.kind === "dir") {
143
+ out.push({
144
+ path: entry.path, exists: true, entries: entry.entries, names: entry.names, gitignored: entry.gitignored,
145
+ plan: "merge-namespaced",
146
+ note: `${entry.entries} ${entry.entries === 1 ? "entry" : "entries"}, ${tracked} — auis writes only names it owns and never deletes yours`,
147
+ });
148
+ } else {
149
+ out.push({
150
+ path: entry.path, exists: true, gitignored: entry.gitignored, plan: "leave",
151
+ note: `exists, ${tracked} — auis leaves it alone`,
152
+ });
153
+ }
154
+ }
155
+ return out;
156
+ }
157
+
158
+ /** Exactly what `auis init` would touch. Same code path, so the two cannot drift. */
159
+ export function installPlan(d, root = ".") {
160
+ const steps = [];
161
+ if (d.framework.name === "next" && d.router.name === "app-router") {
162
+ // The router detection already resolved which of the two roots is real;
163
+ // reuse it rather than testing the CLI's own working directory.
164
+ const base = d.rootLayout.path?.startsWith("src/") || fs.existsSync(path.join(root, "src/app"))
165
+ ? "src/app"
166
+ : "app";
167
+ steps.push({ action: "create", path: `${base}/api/auis/[...auis]/route.ts`, detail: "6 lines — re-exports the bridge handlers" });
168
+ }
169
+ steps.push({ action: "create", path: ".auis/manifest.json", detail: "what auis wrote, so update and uninstall can reverse it" });
170
+ steps.push({ action: "create", path: ".auis/data/", detail: "the comment and edit queues" });
171
+ if (d.rootLayout.path && d.rootLayout.patchable) {
172
+ steps.push({ action: "edit", path: d.rootLayout.path, detail: "+2 lines — one import, one <AuisBuilder /> before </body>" });
173
+ } else if (d.rootLayout.path) {
174
+ steps.push({ action: "print", path: d.rootLayout.path, detail: `${d.rootLayout.bodies} <body> tags — auis prints the two lines for you to place` });
175
+ }
176
+ steps.push({ action: "append", path: ".gitignore", detail: "2 lines, in a delimited block" });
177
+ steps.push({ action: "edit", path: "package.json", detail: "+1 dependency" });
178
+ return steps;
179
+ }
180
+
181
+ export function buildReport(root, cliVersion) {
182
+ const d = detect(root);
183
+ const caps = capabilities(d);
184
+ const summary = { supported: 0, degraded: 0, unsupported: 0 };
185
+ for (const c of caps) summary[c.verdict]++;
186
+ return {
187
+ auisDoctorVersion: DOCTOR_VERSION,
188
+ generatedAt: new Date().toISOString(),
189
+ cliVersion,
190
+ repo: { root, name: d.name, vcs: d.repo.vcs },
191
+ detections: d,
192
+ collisions: collisions(root),
193
+ capabilities: caps,
194
+ plan: installPlan(d, root),
195
+ summary,
196
+ };
197
+ }
198
+
199
+ const MARK = {
200
+ supported: () => color.green("✓"),
201
+ degraded: () => color.yellow("!"),
202
+ unsupported: () => color.red("✗"),
203
+ };
204
+
205
+ function field(label, value) {
206
+ write(` ${color.dim(label.padEnd(12))}${value}`);
207
+ }
208
+
209
+ export function report(doc) {
210
+ const d = doc.detections;
211
+
212
+ write();
213
+ field("Repository", `${color.bold(doc.repo.name)} ${color.dim(doc.repo.root)}`);
214
+ const stack = [
215
+ d.framework.name === "unknown" ? null : `${d.framework.name} ${d.framework.version ?? ""}`.trim(),
216
+ d.router.name === "unknown" || d.router.name === "other" ? null : d.router.name,
217
+ d.react.major ? `react ${d.react.major}` : null,
218
+ d.css.solution === "plain-css" ? "plain css" : `${d.css.solution}${d.css.major ? ` ${d.css.major}` : ""}`,
219
+ ].filter(Boolean);
220
+ field("Stack", stack.join(color.dim(" · ")));
221
+ field("Tokens", d.tokens.customProperties > 0
222
+ ? `${d.tokens.customProperties} custom properties ${color.dim(`in ${d.css.entry}`)}`
223
+ : color.dim("none declared"));
224
+ field("Icons", d.icons.system === "none" ? color.dim("none detected") : d.icons.system);
225
+ field("Reset", `${d.reset.level}${d.reset.signals.length ? color.dim(` · ${d.reset.signals.join(", ")}`) : ""}`);
226
+ field("Dev server", d.devServer.fileWriting
227
+ ? `writes files ${color.dim(`· ${d.devServer.command}`)}`
228
+ : color.dim(d.devServer.command ? `${d.devServer.command} — cannot persist for Auis` : "none found"));
229
+
230
+ write();
231
+ write(` ${color.bold("Capabilities")} ${color.dim(`${doc.summary.supported} supported · ${doc.summary.degraded} degraded · ${doc.summary.unsupported} unsupported`)}`);
232
+ write();
233
+ for (const c of doc.capabilities) {
234
+ write(` ${MARK[c.verdict]()} ${color.bold(c.id.padEnd(20))}${c.because}`);
235
+ if (c.remedy) write(` ${color.dim(" ".repeat(20) + c.remedy)}`);
236
+ }
237
+
238
+ if (doc.collisions.length > 0) {
239
+ write();
240
+ write(` ${color.bold("Already yours")} ${color.dim("auis will not overwrite any of these")}`);
241
+ write();
242
+ for (const c of doc.collisions) {
243
+ write(` ${color.cyan(c.path.padEnd(20))}${color.dim(c.note)}`);
244
+ }
245
+ }
246
+
247
+ write();
248
+ write(` ${color.bold("What installing would touch")} ${color.dim(`${doc.plan.length} places`)}`);
249
+ write();
250
+ for (const step of doc.plan) {
251
+ write(` ${color.dim(step.action.padEnd(8))}${step.path.padEnd(34)}${color.dim(step.detail)}`);
252
+ }
253
+ write();
254
+ write(` ${color.dim("There is no `auis init` yet — this is the footprint it will have.")}`);
255
+
256
+ write();
257
+ write(` ${color.dim("Nothing was written — doctor only reads.")}`);
258
+ write();
259
+ }
260
+
261
+ export async function doctor({ directory = ".", json = false, cliVersion } = {}) {
262
+ const root = path.resolve(directory);
263
+ if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
264
+ process.stderr.write(`\n ${color.red("✗")} ${root} is not a directory.\n\n`);
265
+ return 1;
266
+ }
267
+
268
+ const doc = buildReport(root, cliVersion);
269
+ if (json) {
270
+ process.stdout.write(`${JSON.stringify(doc, null, 2)}\n`);
271
+ return 0;
272
+ }
273
+ report(doc);
274
+ return 0;
275
+ }