promptarch 1.0.0

package/README.md

@@ -0,0 +1,118 @@
+# promptarch
+
+Generate and lint AI coding-agent context files (`CLAUDE.md`, `AGENTS.md`, Cursor `.mdc` rules, GitHub Copilot instructions) straight from your repository.
+
+Powered by the same deterministic linter and Context Pack exporters that run in the [PromptArch](https://promptarch.ai) web app and MCP server, bundled into the CLI, so there's nothing else to install.
+
+- **`lint`** is 100% offline and free: no account, no network. Great for CI.
+- **`init`** extracts your repo's context and generates every agent format in one shot (this one calls the PromptArch API and uses credits).
+
+## Requirements
+
+- Node.js **≥ 18**
+- A PromptArch account + API key **only for `init`** (see [Getting an API key](#getting-an-api-key)). `lint` needs neither.
+
+## Quick start
+
+Lint an existing config without installing anything:
+
+```bash
+npx promptarch lint CLAUDE.md
+```
+
+Or install globally:
+
+```bash
+npm install -g promptarch
+promptarch lint CLAUDE.md AGENTS.md
+```
+
+## Commands
+
+### `promptarch lint <files...>`
+
+Deterministic, offline lint of agent context files. Prints findings and exits non-zero when any **error** is found (add `--strict` to also fail on warnings), so it drops straight into CI.
+
+```bash
+promptarch lint CLAUDE.md
+promptarch lint CLAUDE.md AGENTS.md .cursor/rules/*.mdc
+promptarch lint CLAUDE.md --strict
+```
+
+| Option | Description |
+|--------|-------------|
+| `--strict` | Treat warnings as failures too (not just errors) |
+
+### `promptarch login`
+
+Store your API key (`pk_…`) in `~/.config/promptarch/config.json` (written with `0600` permissions). Required before `init`.
+
+```bash
+promptarch login                  # paste the key when prompted
+promptarch login --key pk_xxx     # non-interactive (CI)
+promptarch login --url https://promptarch-preview.workers.dev   # target a non-prod deploy
+```
+
+| Option | Description |
+|--------|-------------|
+| `--key <key>` | Provide the key non-interactively (for CI) |
+| `--url <url>` | Override the API base URL (saved to config) |
+
+### `promptarch init`
+
+Scan the current repository (package manifest, scripts, directory tree, README, and any existing agent config), generate a canonical **Context Pack** via the API, and write every supported format (`CLAUDE.md`, `AGENTS.md`, Cursor `.mdc`, Copilot instructions).
+
+```bash
+promptarch init --dry-run          # print the extracted payload, no network call
+promptarch init                    # generate + write files into the current directory
+promptarch init --out ./generated  # write to a specific directory
+```
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Print the extracted payload without calling the API (no key needed) |
+| `--out <dir>` | Output directory (default: current directory) |
+
+> `init` consumes credits. The first generation on a new account is free.
+
+Run `promptarch --help` (or `promptarch <command> --help`) and `promptarch --version` at any time.
+
+## Getting an API key
+
+1. Sign in at **[promptarch.ai](https://promptarch.ai)**.
+2. Go to your **Profile → API keys**, create a key (an optional label helps you track it), and copy the `pk_…` value. It's shown **once**.
+3. `promptarch login --key pk_…` (or run `promptarch login` and paste it).
+
+Keys are hashed at rest and can be revoked from the same page.
+
+## Configuration
+
+Resolution order (first match wins):
+
+| Setting | Env var | Config file | Default |
+|---------|---------|-------------|---------|
+| API key | `PROMPTARCH_API_KEY` | `apiKey` in `~/.config/promptarch/config.json` | - |
+| API URL | `PROMPTARCH_API_URL` | `apiUrl` in config | `https://promptarch.ai` |
+
+Env vars are handy in CI:
+
+```bash
+PROMPTARCH_API_KEY=pk_xxx promptarch init --out ./generated
+```
+
+## Related
+
+- **[PromptArch](https://promptarch.ai)** - the web app (prompt builder + Context Studio)
+- **`promptarch-mcp`** - MCP server exposing `lint` / `generate` tools to agents over Streamable HTTP
+
+## Develop
+
+```bash
+npm install
+npm run build      # tsup → dist/index.js
+node dist/index.js lint ../CLAUDE.md
+```
+
+## License
+
+Proprietary. © PromptArch. All rights reserved. This CLI is provided for use with the PromptArch service; it is not open-source, and no rights to copy, modify, or redistribute the code are granted.

package/dist/index.js

@@ -0,0 +1,955 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/init.ts
+import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
+import { dirname, join as join3, resolve } from "path";
+
+// ../packages/core/context-model/types.ts
+var SECTION_ORDER = [
+  "overview",
+  "structure",
+  "commands",
+  "testing",
+  "style",
+  "git",
+  "boundaries",
+  "custom"
+];
+function sortSections(sections) {
+  return [...sections].sort(
+    (a, b) => SECTION_ORDER.indexOf(a.id) - SECTION_ORDER.indexOf(b.id)
+  );
+}
+
+// ../packages/core/linter/types.ts
+var SEVERITY_PENALTY = {
+  error: 15,
+  warn: 7,
+  info: 2
+};
+var SIZE_BUDGETS = {
+  claudeMdWarnLines: 300,
+  claudeMdErrorChars: 4e4,
+  cursorMdcWarnLines: 500,
+  agentsMdErrorBytes: 32 * 1024,
+  // Codex truncation
+  copilotWarnLines: 400
+};
+
+// ../packages/core/context-model/exporters.ts
+function renderMarkdown(pack, includeTitle = true) {
+  const parts = [];
+  if (includeTitle && pack.projectName) {
+    parts.push(`# ${pack.projectName}
+`);
+  }
+  for (const s of sortSections(pack.sections)) {
+    parts.push(`## ${s.title}
+
+${s.body.trim()}
+`);
+  }
+  return parts.join("\n").trim() + "\n";
+}
+function withinBudget(content, maxChars) {
+  if (content.length <= maxChars) return content;
+  return content.slice(0, maxChars - 80).trimEnd() + "\n\n<!-- truncated to stay within tool size budget -->\n";
+}
+function exportAgentsMd(pack) {
+  const content = withinBudget(
+    renderMarkdown(pack),
+    SIZE_BUDGETS.agentsMdErrorBytes
+  );
+  return [{ path: "AGENTS.md", content }];
+}
+function exportClaudeMd(pack, mode = "full") {
+  if (mode === "import") {
+    const name = pack.projectName ?? "Project";
+    return [
+      {
+        path: "CLAUDE.md",
+        content: `# ${name}
+
+Project context lives in AGENTS.md.
+
+@AGENTS.md
+`
+      }
+    ];
+  }
+  const content = withinBudget(
+    renderMarkdown(pack),
+    SIZE_BUDGETS.claudeMdErrorChars
+  );
+  return [{ path: "CLAUDE.md", content }];
+}
+function mdcFrontmatter(section) {
+  const globs = section.scope?.globs ?? [];
+  const alwaysApply = globs.length === 0;
+  const lines = [
+    "---",
+    `description: ${section.title}`,
+    `globs: ${globs.join(", ")}`,
+    `alwaysApply: ${alwaysApply}`,
+    "---"
+  ];
+  return lines.join("\n");
+}
+function exportCursorMdc(pack) {
+  return sortSections(pack.sections).map((section) => {
+    const body = `${mdcFrontmatter(section)}
+
+# ${section.title}
+
+${section.body.trim()}
+`;
+    return {
+      path: `.cursor/rules/${section.id}.mdc`,
+      content: body
+    };
+  });
+}
+function exportCopilotInstructions(pack) {
+  const files = [];
+  const rootSections = sortSections(pack.sections).filter(
+    (s) => !s.scope?.globs?.length
+  );
+  const scopedSections = sortSections(pack.sections).filter(
+    (s) => s.scope?.globs?.length
+  );
+  if (rootSections.length) {
+    files.push({
+      path: ".github/copilot-instructions.md",
+      content: renderMarkdown({ ...pack, sections: rootSections })
+    });
+  }
+  for (const s of scopedSections) {
+    const applyTo = (s.scope?.globs ?? []).join(", ");
+    files.push({
+      path: `.github/instructions/${s.id}.instructions.md`,
+      content: `---
+applyTo: "${applyTo}"
+---
+
+# ${s.title}
+
+${s.body.trim()}
+`
+    });
+  }
+  return files;
+}
+function exportPack(pack, formats, opts = {}) {
+  const out = [];
+  for (const f of formats) {
+    switch (f) {
+      case "agents_md":
+        out.push(...exportAgentsMd(pack));
+        break;
+      case "claude_md":
+        out.push(...exportClaudeMd(pack, opts.claudeMode ?? "full"));
+        break;
+      case "cursor_mdc":
+        out.push(...exportCursorMdc(pack));
+        break;
+      case "copilot_instructions":
+        out.push(...exportCopilotInstructions(pack));
+        break;
+    }
+  }
+  return out;
+}
+var ALL_EXPORT_FORMATS = [
+  "agents_md",
+  "claude_md",
+  "cursor_mdc",
+  "copilot_instructions"
+];
+
+// ../packages/core/context-model/parse.ts
+var VALID_IDS = [
+  "overview",
+  "commands",
+  "testing",
+  "structure",
+  "style",
+  "git",
+  "boundaries",
+  "custom"
+];
+function parseContextModel(text) {
+  const match = text.match(/<context_model>([\s\S]*?)<\/context_model>/);
+  const fallback = () => ({
+    sections: [{ id: "overview", title: "Overview", body: text.trim() }]
+  });
+  if (!match) return fallback();
+  let raw = match[1].trim();
+  raw = raw.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed.sections) || parsed.sections.length === 0) {
+      return fallback();
+    }
+    const sections = parsed.sections.filter((s) => typeof s.body === "string" && s.body.trim().length > 0).map((s) => {
+      const id = VALID_IDS.includes(s.id) ? s.id : "custom";
+      const section = {
+        id,
+        title: s.title?.trim() || id,
+        body: (s.body ?? "").trim()
+      };
+      if (Array.isArray(s.scope?.globs) && s.scope.globs.length) {
+        section.scope = { globs: s.scope.globs.filter(Boolean) };
+      }
+      return section;
+    });
+    if (!sections.length) return fallback();
+    return { projectName: parsed.projectName?.trim(), sections };
+  } catch {
+    return fallback();
+  }
+}
+
+// src/extract.ts
+import { readdir, readFile } from "fs/promises";
+import { basename, join } from "path";
+var IGNORE = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  ".next",
+  ".open-next",
+  ".wrangler",
+  "build",
+  "coverage",
+  ".turbo",
+  "out"
+]);
+var STACK_HINTS = [
+  [/^next$/, "Next.js"],
+  [/^react$/, "React"],
+  [/^react-native$|^expo$/, "React Native / Expo"],
+  [/^vue$/, "Vue"],
+  [/^svelte$/, "Svelte"],
+  [/^@angular\/core$/, "Angular"],
+  [/^express$|^fastify$|^koa$/, "Node HTTP server"],
+  [/^@supabase\//, "Supabase"],
+  [/^prisma$|^@prisma\//, "Prisma"],
+  [/^drizzle-orm$/, "Drizzle"],
+  [/^tailwindcss$/, "Tailwind CSS"],
+  [/^typescript$/, "TypeScript"],
+  [/^vitest$|^jest$/, "unit tests"],
+  [/^@playwright\/test$|^playwright$/, "Playwright E2E"]
+];
+async function extractRepo(cwd) {
+  const pkg = await readJson(join(cwd, "package.json"));
+  const name = pkg?.name || basename(cwd);
+  const description = pkg?.description || await firstReadmeParagraph(cwd) || "";
+  return {
+    name,
+    description,
+    techStack: detectStack(pkg),
+    tree: await buildTree(cwd),
+    commands: formatScripts(pkg?.scripts),
+    conventions: await readExistingConfig(cwd)
+  };
+}
+async function readJson(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function detectStack(pkg) {
+  if (!pkg) return "";
+  const deps = {
+    ...pkg.dependencies ?? {},
+    ...pkg.devDependencies ?? {}
+  };
+  const names = Object.keys(deps);
+  const found = /* @__PURE__ */ new Set();
+  for (const [pattern, label] of STACK_HINTS) {
+    if (names.some((n) => pattern.test(n))) found.add(label);
+  }
+  return [...found].join(", ");
+}
+function formatScripts(scripts) {
+  if (!scripts || typeof scripts !== "object") return "";
+  return Object.entries(scripts).map(([k, v]) => `npm run ${k}: ${v}`).join("\n");
+}
+async function buildTree(cwd) {
+  const lines = [];
+  async function walk(dir, prefix, depth) {
+    if (depth > 2) return;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    const visible = entries.filter((e) => !IGNORE.has(e.name) && !e.name.startsWith(".")).sort((a, b) => a.name.localeCompare(b.name)).slice(0, 40);
+    for (const e of visible) {
+      lines.push(`${prefix}${e.name}${e.isDirectory() ? "/" : ""}`);
+      if (e.isDirectory()) await walk(join(dir, e.name), prefix + "  ", depth + 1);
+    }
+  }
+  await walk(cwd, "", 0);
+  return lines.slice(0, 200).join("\n");
+}
+async function firstReadmeParagraph(cwd) {
+  for (const name of ["README.md", "readme.md", "Readme.md"]) {
+    try {
+      const text = await readFile(join(cwd, name), "utf8");
+      const para = text.split("\n").filter((l) => l.trim() && !l.trim().startsWith("#") && !l.startsWith("![")).slice(0, 3).join(" ").trim();
+      if (para) return para.slice(0, 400);
+    } catch {
+    }
+  }
+  return "";
+}
+async function readExistingConfig(cwd) {
+  for (const name of ["CLAUDE.md", "AGENTS.md", ".cursorrules"]) {
+    try {
+      const text = await readFile(join(cwd, name), "utf8");
+      if (text.trim()) return text.slice(0, 4e3);
+    } catch {
+    }
+  }
+  return "";
+}
+
+// src/config.ts
+import { homedir } from "os";
+import { join as join2 } from "path";
+import { mkdir, readFile as readFile2, writeFile } from "fs/promises";
+var CONFIG_DIR = join2(homedir(), ".config", "promptarch");
+var CONFIG_PATH = join2(CONFIG_DIR, "config.json");
+var DEFAULT_API_URL = "https://promptarch.ai";
+async function loadConfig() {
+  try {
+    return JSON.parse(await readFile2(CONFIG_PATH, "utf8"));
+  } catch {
+    return {};
+  }
+}
+async function saveConfig(cfg) {
+  await mkdir(CONFIG_DIR, { recursive: true });
+  await writeFile(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n", {
+    mode: 384
+  });
+}
+function resolveApiUrl(cfg) {
+  return process.env.PROMPTARCH_API_URL || cfg.apiUrl || DEFAULT_API_URL;
+}
+function resolveApiKey(cfg) {
+  return process.env.PROMPTARCH_API_KEY || cfg.apiKey;
+}
+
+// src/commands/init.ts
+async function initCmd(opts) {
+  const cwd = process.cwd();
+  const info = await extractRepo(cwd);
+  const payload = {
+    domain: "ai_skills_rules",
+    subType: "context_pack",
+    targetModel: "Claude",
+    answers: {
+      skill_name: info.name,
+      skill_description: info.description,
+      tech_stack: info.techStack,
+      repo_structure: info.tree,
+      commands: info.commands,
+      coding_conventions: info.conventions,
+      _subType: "context_pack"
+    }
+  };
+  if (opts.dryRun) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  const cfg = await loadConfig();
+  const key = resolveApiKey(cfg);
+  if (!key) {
+    console.error(
+      "No API key. Run `promptarch login` first (or set PROMPTARCH_API_KEY)."
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const url = `${resolveApiUrl(cfg)}/api/build`;
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${key}`
+      },
+      body: JSON.stringify(payload)
+    });
+  } catch {
+    console.error(`Network error contacting ${url}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (res.status === 401) {
+    console.error("Unauthorized: check your API key (`promptarch login`).");
+    process.exitCode = 1;
+    return;
+  }
+  if (res.status === 402) {
+    console.error("Insufficient credits. Top up at promptarch.ai.");
+    process.exitCode = 1;
+    return;
+  }
+  if (!res.ok) {
+    console.error(`Build failed (HTTP ${res.status}).`);
+    process.exitCode = 1;
+    return;
+  }
+  const body = await res.json();
+  if (!body.prompt) {
+    console.error("Empty response from the server.");
+    process.exitCode = 1;
+    return;
+  }
+  const pack = parseContextModel(body.prompt);
+  const files = exportPack(pack, ALL_EXPORT_FORMATS);
+  const outDir = opts.out ? resolve(cwd, opts.out) : cwd;
+  for (const f of files) {
+    const dest = join3(outDir, f.path);
+    await mkdir2(dirname(dest), { recursive: true });
+    await writeFile2(dest, f.content, "utf8");
+    console.log(`wrote ${f.path}`);
+  }
+  console.log(`
+\u2713 Generated ${files.length} file(s) in ${outDir}`);
+}
+
+// src/commands/lint.ts
+import { readFile as readFile3 } from "fs/promises";
+
+// ../packages/core/linter/detect.ts
+function detectFormat(content, filename) {
+  const name = (filename ?? "").toLowerCase();
+  if (name.endsWith(".mdc") || name.includes(".cursor/rules")) return "cursor_mdc";
+  if (name.includes("copilot-instructions")) return "copilot_instructions";
+  if (name.includes("claude.md") || name === "claude.md") return "claude_md";
+  if (name.includes("agents.md") || name === "agents.md") return "agents_md";
+  if (name === "memory.md" || name.endsWith("/memory.md") || name.includes("/memory/") || name.startsWith("memory/")) {
+    return "memory_file";
+  }
+  const head = content.slice(0, 400);
+  if (/^#\s*memory policy/im.test(head)) return "memory_file";
+  if (/^---[\s\S]*?\b(globs|alwaysApply)\b[\s\S]*?---/.test(head)) {
+    return "cursor_mdc";
+  }
+  if (/copilot/i.test(head)) return "copilot_instructions";
+  if (/\bAGENTS\b/.test(content) && !/\bCLAUDE\b/.test(content)) {
+    return "agents_md";
+  }
+  return "claude_md";
+}
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!match) return { frontmatter: null, bodyStartLine: 1 };
+  const block = match[1];
+  const fm = {};
+  for (const rawLine of block.split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim();
+    fm[key] = value;
+  }
+  const bodyStartLine = match[0].split("\n").length;
+  return { frontmatter: fm, bodyStartLine };
+}
+
+// ../packages/core/linter/rules.ts
+function lineOf(content, index) {
+  return content.slice(0, index).split("\n").length;
+}
+function ruleLength(content, format) {
+  const findings = [];
+  const lines = content.split("\n").length;
+  const chars = content.length;
+  const bytes = new TextEncoder().encode(content).length;
+  if (format === "claude_md") {
+    if (chars > SIZE_BUDGETS.claudeMdErrorChars) {
+      findings.push({
+        ruleId: "length/claude-md-chars",
+        severity: "error",
+        message: `CLAUDE.md is ${chars.toLocaleString()} characters (>${SIZE_BUDGETS.claudeMdErrorChars.toLocaleString()}). Oversized context gets ignored. Trim aggressively.`
+      });
+    } else if (lines > SIZE_BUDGETS.claudeMdWarnLines) {
+      findings.push({
+        ruleId: "length/claude-md-lines",
+        severity: "warn",
+        message: `CLAUDE.md is ${lines} lines (>${SIZE_BUDGETS.claudeMdWarnLines}). Anthropic warns bloat causes instructions to be ignored, and both frontier labs now report leaner prompts score higher (OpenAI: 10\u201315% on internal evals).`
+      });
+    }
+  }
+  if (format === "cursor_mdc" && lines > SIZE_BUDGETS.cursorMdcWarnLines) {
+    findings.push({
+      ruleId: "length/cursor-lines",
+      severity: "warn",
+      message: `Cursor rule is ${lines} lines (>${SIZE_BUDGETS.cursorMdcWarnLines}). Split into focused, scoped rules.`
+    });
+  }
+  if (format === "agents_md" && bytes > SIZE_BUDGETS.agentsMdErrorBytes) {
+    findings.push({
+      ruleId: "length/agents-bytes",
+      severity: "error",
+      message: `AGENTS.md is ${(bytes / 1024).toFixed(1)}KiB (>32KiB). Codex truncates beyond 32KiB. Content past the cap is silently dropped.`
+    });
+  }
+  if (format === "copilot_instructions" && lines > SIZE_BUDGETS.copilotWarnLines) {
+    findings.push({
+      ruleId: "length/copilot-lines",
+      severity: "warn",
+      message: `Copilot instructions are ${lines} lines. Keep them short and high-signal.`
+    });
+  }
+  return findings;
+}
+function ruleCursorFrontmatter(content, format) {
+  if (format !== "cursor_mdc") return [];
+  const findings = [];
+  const { frontmatter } = parseFrontmatter(content);
+  if (!frontmatter) {
+    findings.push({
+      ruleId: "cursor/missing-frontmatter",
+      severity: "error",
+      message: "Cursor .mdc requires YAML frontmatter. A plain .md file in .cursor/rules is ignored.",
+      line: 1
+    });
+    return findings;
+  }
+  for (const key of ["description", "globs", "alwaysApply"]) {
+    if (!(key in frontmatter)) {
+      findings.push({
+        ruleId: `cursor/frontmatter-${key}`,
+        severity: key === "description" ? "warn" : "info",
+        message: `Cursor .mdc frontmatter is missing "${key}". Cursor uses description/globs/alwaysApply to decide when to apply the rule.`,
+        line: 1
+      });
+    }
+  }
+  if ("alwaysApply" in frontmatter && !/^(true|false)$/i.test(frontmatter.alwaysApply.trim())) {
+    findings.push({
+      ruleId: "cursor/alwaysApply-boolean",
+      severity: "warn",
+      message: `"alwaysApply" should be true or false (got "${frontmatter.alwaysApply}").`,
+      line: 1
+    });
+  }
+  return findings;
+}
+var VAGUE_PHRASES = [
+  "be helpful",
+  "write clean code",
+  "write good code",
+  "do your best",
+  "as an ai",
+  "you are a helpful assistant",
+  "follow best practices",
+  "use good judgment",
+  "be professional"
+];
+function ruleVagueLanguage(content) {
+  const findings = [];
+  const lower = content.toLowerCase();
+  for (const phrase of VAGUE_PHRASES) {
+    const idx = lower.indexOf(phrase);
+    if (idx !== -1) {
+      findings.push({
+        ruleId: "vague/low-signal",
+        severity: "warn",
+        message: `Vague instruction "${phrase}": Anthropic's exclude table flags this as noise. Replace with a concrete, checkable rule.`,
+        line: lineOf(content, idx)
+      });
+    }
+  }
+  return findings;
+}
+var COMMON_COMMAND_PATTERNS = [
+  /\bnpm install\b/i,
+  /\bgit (commit|add|push)\b/i,
+  /\bpytest\b/i,
+  /\byarn install\b/i,
+  /\bpip install\b/i
+];
+function ruleAntiPatterns(content) {
+  const findings = [];
+  const commonHits = COMMON_COMMAND_PATTERNS.filter((re) => re.test(content));
+  if (commonHits.length >= 2) {
+    findings.push({
+      ruleId: "antipattern/common-commands",
+      severity: "info",
+      message: "Documents standard tooling commands (npm/git/pytest). Agents already know these. Spend the budget on project-specific facts."
+    });
+  }
+  const todo = content.match(/\b(TODO|FIXME|XXX)\b/);
+  if (todo) {
+    findings.push({
+      ruleId: "antipattern/unresolved-todo",
+      severity: "info",
+      message: `Contains an unresolved ${todo[1]}. Resolve or remove before shipping this as agent context.`,
+      line: lineOf(content, todo.index ?? 0)
+    });
+  }
+  return findings;
+}
+var REASONING_TRANSCRIPTION_PHRASES = [
+  "transcribe your thinking",
+  "transcribe your reasoning",
+  "show your full reasoning",
+  "reveal your reasoning",
+  "output your chain of thought",
+  "echo your reasoning",
+  "include your internal reasoning"
+];
+var REASONING_SCAFFOLDING_PHRASES = [
+  "think step by step",
+  "think step-by-step",
+  "show your work",
+  "explain your reasoning"
+];
+function ruleReasoningEcho(content) {
+  const findings = [];
+  const lower = content.toLowerCase();
+  for (const phrase of REASONING_TRANSCRIPTION_PHRASES) {
+    const idx = lower.indexOf(phrase);
+    if (idx !== -1) {
+      findings.push({
+        ruleId: "antipattern/reasoning-echo",
+        severity: "warn",
+        message: `Instruction asks the model to echo internal reasoning ("${phrase}"). On Claude Fable 5 this triggers reasoning_extraction refusals. Read structured thinking blocks via the API instead.`,
+        line: lineOf(content, idx)
+      });
+    }
+  }
+  for (const phrase of REASONING_SCAFFOLDING_PHRASES) {
+    const idx = lower.indexOf(phrase);
+    if (idx !== -1) {
+      findings.push({
+        ruleId: "antipattern/reasoning-echo",
+        severity: "warn",
+        message: `Chain-of-thought scaffolding ("${phrase}"): current reasoning models reason internally; this adds noise and can degrade output. Remove it, or move reasoning needs to the effort/thinking API controls.`,
+        line: lineOf(content, idx)
+      });
+    }
+  }
+  return findings;
+}
+var VERBOSITY_PHRASES = [
+  "be concise",
+  "keep it short",
+  "keep responses brief",
+  "answer briefly",
+  "respond concisely"
+];
+function ruleVerbosityInstruction(content) {
+  const findings = [];
+  const lower = content.toLowerCase();
+  for (const phrase of VERBOSITY_PHRASES) {
+    const idx = lower.indexOf(phrase);
+    if (idx !== -1) {
+      findings.push({
+        ruleId: "antipattern/verbosity-instruction",
+        severity: "info",
+        message: `Verbosity instruction "${phrase}": on current models verbosity is an API parameter (text.verbosity on GPT-5.6; effort on Claude). Prompt-level brevity lines double-steer and can make responses too brief; keep only if re-tested.`,
+        line: lineOf(content, idx)
+      });
+    }
+  }
+  return findings;
+}
+var COUNTDOWN_PHRASES = [
+  "tokens remaining",
+  "remaining tokens",
+  "tokens left",
+  "context budget:"
+];
+var NEGATION_MARKERS = ["never", "don't", "do not", "avoid", "without"];
+function ruleContextCountdown(content) {
+  const findings = [];
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const lower = lines[i].toLowerCase();
+    const hit = COUNTDOWN_PHRASES.find((p) => lower.includes(p));
+    if (!hit) continue;
+    if (NEGATION_MARKERS.some((n) => lower.includes(n))) continue;
+    findings.push({
+      ruleId: "antipattern/context-countdown",
+      severity: "warn",
+      message: `Surfaces a running context budget to the model ("${hit}"). Models shown a token countdown may abandon the task and suggest a new session. Expose action thresholds ("compact now") instead.`,
+      line: i + 1
+    });
+  }
+  return findings;
+}
+var EMPHASIS_RE = /\b(IMPORTANT|CRITICAL|ALWAYS|NEVER|MUST(?: NOT)?|DO NOT)\b/g;
+var EMPHASIS_THRESHOLD = 8;
+function ruleEmphasisInflation(content) {
+  const matches = [...content.matchAll(EMPHASIS_RE)];
+  if (matches.length < EMPHASIS_THRESHOLD) return [];
+  const anchor = matches[EMPHASIS_THRESHOLD - 1];
+  return [
+    {
+      ruleId: "antipattern/emphasis-inflation",
+      severity: "info",
+      message: `${matches.length} ALL-CAPS emphasis markers (IMPORTANT/ALWAYS/NEVER/MUST\u2026). Emphasis works by contrast. Reserve caps for the few non-negotiable rules; on current frontier models leaner prompts outperform prescriptive ones.`,
+      line: lineOf(content, anchor.index ?? 0)
+    }
+  ];
+}
+var DUPLICATE_MIN_LENGTH = 20;
+var DUPLICATE_MAX_FINDINGS = 3;
+function ruleDuplicateLine(content) {
+  const findings = [];
+  const lines = content.split("\n");
+  const seen = /* @__PURE__ */ new Map();
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (raw.trimStart().startsWith("```")) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const normalized = raw.trim();
+    if (normalized.length < DUPLICATE_MIN_LENGTH) continue;
+    const first = seen.get(normalized);
+    if (first === void 0) {
+      seen.set(normalized, i + 1);
+      continue;
+    }
+    if (findings.length >= DUPLICATE_MAX_FINDINGS) break;
+    findings.push({
+      ruleId: "antipattern/duplicate-line",
+      severity: "info",
+      message: `Line ${i + 1} repeats line ${first} verbatim ("${normalized.slice(0, 60)}${normalized.length > 60 ? "\u2026" : ""}"). State each rule once. Update the original instead of duplicating; duplicated rules drift apart and dilute the context.`,
+      line: i + 1
+    });
+  }
+  return findings;
+}
+function ruleMemoryFile(content, format) {
+  if (format !== "memory_file") return [];
+  const lines = content.split("\n");
+  let i = 0;
+  while (i < lines.length && lines[i].trim() === "") i++;
+  const hasHeading = lines[i]?.trim().startsWith("#") ?? false;
+  if (hasHeading) i++;
+  while (i < lines.length && lines[i].trim() === "") i++;
+  const summary = lines[i]?.trim() ?? "";
+  if (!hasHeading || summary === "" || summary.startsWith("#")) {
+    return [
+      {
+        ruleId: "memory/missing-summary-line",
+        severity: "warn",
+        message: "A memory file should open with a title and a one-line summary: one lesson per file, summary at the top, so the index and future reads stay cheap.",
+        line: 1
+      }
+    ];
+  }
+  if (summary.length > 200) {
+    return [
+      {
+        ruleId: "memory/missing-summary-line",
+        severity: "warn",
+        message: `The line after the title runs ${summary.length} characters. Keep the top-of-file summary to one short line; details go below.`,
+        line: i + 1
+      }
+    ];
+  }
+  return [];
+}
+var SECRET_PATTERNS = [
+  { re: /\bsk-[a-zA-Z0-9]{16,}\b/, label: "OpenAI-style API key (sk-\u2026)" },
+  { re: /\bsk-ant-[a-zA-Z0-9-]{16,}\b/, label: "Anthropic API key (sk-ant-\u2026)" },
+  { re: /\bghp_[a-zA-Z0-9]{20,}\b/, label: "GitHub token (ghp_\u2026)" },
+  { re: /\bAKIA[0-9A-Z]{16}\b/, label: "AWS access key (AKIA\u2026)" },
+  { re: /\bxox[baprs]-[a-zA-Z0-9-]{10,}\b/, label: "Slack token (xox\u2026)" }
+];
+var DANGEROUS_PATTERNS = [
+  { re: /rm\s+-rf\s+\/(?:\s|$)/, label: "rm -rf /" },
+  { re: /curl[^\n|]*\|\s*(?:sudo\s+)?(?:bash|sh)\b/, label: "curl | bash" },
+  { re: /wget[^\n|]*\|\s*(?:sudo\s+)?(?:bash|sh)\b/, label: "wget | sh" }
+];
+function ruleSecurity(content) {
+  const findings = [];
+  for (const { re, label } of SECRET_PATTERNS) {
+    const m = content.match(re);
+    if (m) {
+      findings.push({
+        ruleId: "security/secret",
+        severity: "error",
+        message: `Possible leaked secret (${label}). Never commit credentials into agent context.`,
+        line: lineOf(content, m.index ?? 0)
+      });
+    }
+  }
+  for (const { re, label } of DANGEROUS_PATTERNS) {
+    const m = content.match(re);
+    if (m) {
+      findings.push({
+        ruleId: "security/dangerous-command",
+        severity: "warn",
+        message: `Dangerous command in instructions (${label}). An agent may execute this literally.`,
+        line: lineOf(content, m.index ?? 0)
+      });
+    }
+  }
+  return findings;
+}
+function ruleSubstance(content) {
+  if (content.trim().length < 80) {
+    return [
+      {
+        ruleId: "substance/too-short",
+        severity: "warn",
+        message: "Very little content. An effective agent config should describe the project, commands, and conventions."
+      }
+    ];
+  }
+  return [];
+}
+function runRules(content, format) {
+  return [
+    ...ruleLength(content, format),
+    ...ruleCursorFrontmatter(content, format),
+    ...ruleVagueLanguage(content),
+    ...ruleAntiPatterns(content),
+    ...ruleReasoningEcho(content),
+    ...ruleVerbosityInstruction(content),
+    ...ruleContextCountdown(content),
+    ...ruleEmphasisInflation(content),
+    ...ruleDuplicateLine(content),
+    ...ruleMemoryFile(content, format),
+    ...ruleSecurity(content),
+    ...ruleSubstance(content)
+  ];
+}
+
+// ../packages/core/linter/index.ts
+function scoreToGrade(score) {
+  if (score >= 90) return "A";
+  if (score >= 80) return "B";
+  if (score >= 70) return "C";
+  if (score >= 60) return "D";
+  return "F";
+}
+function computeScore(findings) {
+  const penalty = findings.reduce(
+    (sum, f) => sum + SEVERITY_PENALTY[f.severity],
+    0
+  );
+  return Math.max(0, 100 - penalty);
+}
+function lint(content, opts = {}) {
+  const format = opts.format ?? detectFormat(content, opts.filename);
+  const findings = runRules(content, format).sort((a, b) => {
+    const order = { error: 0, warn: 1, info: 2 };
+    return order[a.severity] - order[b.severity];
+  });
+  const objectiveScore = computeScore(findings);
+  return {
+    format,
+    objectiveScore,
+    grade: scoreToGrade(objectiveScore),
+    findings
+  };
+}
+
+// src/commands/lint.ts
+async function lintCmd(files, opts) {
+  if (files.length === 0) {
+    console.error("Usage: promptarch lint <file> [more files...]");
+    process.exitCode = 1;
+    return;
+  }
+  let failed = false;
+  for (const file of files) {
+    let content;
+    try {
+      content = await readFile3(file, "utf8");
+    } catch {
+      console.error(`\u2717 ${file}: cannot read file`);
+      failed = true;
+      continue;
+    }
+    const report = lint(content, { filename: file });
+    printReport(file, report);
+    if (report.findings.some((f) => f.severity === "error")) failed = true;
+    if (opts.strict && report.findings.some((f) => f.severity === "warn")) {
+      failed = true;
+    }
+  }
+  if (failed) process.exitCode = 1;
+}
+function printReport(file, report) {
+  console.log(
+    `
+${file} - grade ${report.grade} (${report.objectiveScore}/100, ${report.format})`
+  );
+  if (report.findings.length === 0) {
+    console.log("  \u2713 no findings");
+    return;
+  }
+  for (const f of report.findings) {
+    const mark = f.severity === "error" ? "\u2717" : f.severity === "warn" ? "\u26A0" : "\xB7";
+    const loc = f.line ? `line ${f.line}` : "";
+    console.log(
+      `  ${mark} ${f.severity.padEnd(5)} ${loc.padEnd(8)} ${f.ruleId}: ${f.message}`
+    );
+  }
+}
+
+// src/commands/login.ts
+import { createInterface } from "readline";
+async function login(opts) {
+  let key = opts.key;
+  if (!key) {
+    key = (await prompt("Paste your PromptArch API key (pk_...): ")).trim();
+  }
+  if (!key.startsWith("pk_")) {
+    console.error("Invalid key: expected a pk_... key. Create one in Settings.");
+    process.exitCode = 1;
+    return;
+  }
+  const cfg = await loadConfig();
+  cfg.apiKey = key;
+  if (opts.url) cfg.apiUrl = opts.url;
+  await saveConfig(cfg);
+  console.log(`Saved credentials to ${CONFIG_PATH}`);
+}
+function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(
+    (resolve2) => rl.question(question, (answer) => {
+      rl.close();
+      resolve2(answer);
+    })
+  );
+}
+
+// src/index.ts
+var program = new Command();
+program.name("promptarch").description(
+  "Generate and lint AI coding-agent context files (CLAUDE.md, AGENTS.md, Cursor rules) from your repo."
+).version("0.1.0");
+program.command("login").description("Store a PromptArch API key (pk_...) in ~/.config/promptarch").option("--key <key>", "API key (non-interactive; for CI)").option("--url <url>", "Override the API base URL").action(login);
+program.command("lint").description("Lint agent context files offline (deterministic, free, CI-friendly)").argument("<files...>", "Files to lint (CLAUDE.md, AGENTS.md, *.mdc, ...)").option("--strict", "Fail on warnings too, not just errors").action((files, opts) => lintCmd(files, opts));
+program.command("init").description("Extract repo context and generate CLAUDE.md / AGENTS.md / Cursor / Copilot files").option("--dry-run", "Print the extracted payload without calling the API").option("--out <dir>", "Output directory (default: current directory)").action(initCmd);
+program.parseAsync().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "promptarch",
+  "version": "1.0.0",
+  "description": "Generate and lint AI coding-agent context files (CLAUDE.md, AGENTS.md, Cursor rules) from your repo.",
+  "keywords": [
+    "claude",
+    "cursor",
+    "agents.md",
+    "claude.md",
+    "ai",
+    "context-engineering",
+    "linter"
+  ],
+  "license": "UNLICENSED",
+  "homepage": "https://promptarch.ai",
+  "type": "module",
+  "bin": {
+    "promptarch": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "@types/node": "^22.9.0"
+  }
+}