@akanjs/cli 2.4.0 → 2.4.1-rc.1

package/index-hwzpw9c1.js

@@ -0,0 +1,202 @@
+// @bun
+import {
+  AkanContextAnalyzer
+} from "./index-8rc0bm04.js";
+import {
+  Prompter
+} from "./index-qaq13qk3.js";
+import {
+  runner,
+  script
+} from "./index-hdqztm58.js";
+
+// pkgs/@akanjs/cli/agent/agent.script.ts
+import { Logger } from "akanjs/common";
+
+// pkgs/@akanjs/cli/agent/agent.runner.ts
+var targetPaths = {
+  cursor: ".cursor/rules/akan.mdc",
+  "agents-md": "AGENTS.md",
+  claude: "CLAUDE.md"
+};
+var AGENT_BLOCK_START = "<!-- akan:agent:start -->";
+var AGENT_BLOCK_END = "<!-- akan:agent:end -->";
+var SAMPLE_ARTIFACTS = [
+  { probe: "lib/task/task.constant.ts", target: "lib/task", label: "sample database module" },
+  { probe: "lib/_noti/noti.service.ts", target: "lib/_noti", label: "sample service module" },
+  {
+    probe: "lib/__scalar/workHistory/workHistory.dictionary.ts",
+    target: "lib/__scalar/workHistory",
+    label: "sample scalar module"
+  },
+  { probe: "page/task/_index.tsx", target: "page/task", label: "sample task pages" }
+];
+var DEFAULT_INDEX_MARKER = "Akan.js template";
+var renderSampleCleanup = async (workspace, appNames) => {
+  const items = [];
+  for (const appName of appNames) {
+    for (const artifact of SAMPLE_ARTIFACTS) {
+      if (await workspace.exists(`apps/${appName}/${artifact.probe}`)) {
+        items.push(`- \`apps/${appName}/${artifact.target}\` \u2014 ${artifact.label}; delete it once you no longer need the reference.`);
+      }
+    }
+    const indexPath = `apps/${appName}/page/_index.tsx`;
+    if (await workspace.exists(indexPath)) {
+      const content = await workspace.readFile(indexPath).catch(() => "");
+      if (content.includes(DEFAULT_INDEX_MARKER)) {
+        items.push(`- \`${indexPath}\` \u2014 default Akan landing page; replace it with your own home page.`);
+      }
+    }
+  }
+  if (items.length === 0)
+    return "";
+  return `## Start Clean (Remove Scaffolded Samples)
+
+This workspace was scaffolded with reference samples so the Akan conventions are visible in real code. They are
+not part of your product. Before building real features, remove the samples below and run \`akan sync <app>\`:
+
+${items.join(`
+`)}
+
+Keep a sample only while you are still learning its pattern; delete it once your own modules cover the same ground.
+
+`;
+};
+var renderManagedBlock = async (workspace) => {
+  const context = await AkanContextAnalyzer.analyze(workspace);
+  const frameworkGuide = await Prompter.getInstruction("framework");
+  const sampleCleanup = await renderSampleCleanup(workspace, context.apps.map((app) => app.name));
+  return `## Workspace
+
+- Repo: ${context.repoName}
+- Apps: ${context.apps.map((app) => app.name).join(", ") || "none"}
+- Libraries: ${context.libs.map((lib) => lib.name).join(", ") || "none"}
+- Packages: ${context.pkgs.map((pkg) => pkg.name).join(", ") || "none"}
+
+${sampleCleanup}## Akan Module Abstracts
+
+- Before changing a domain, service, or scalar module, read its \`*.abstract.md\` file first.
+- Update the abstract when business invariants, workflows, or public behavior change.
+- Do not update the abstract for formatting-only, import-only, or style-only changes.
+- Service modules live in \`lib/_<service>\`, but their abstract file is \`<service>.abstract.md\`.
+
+## Generated Files
+
+Do not hand-edit generated Akan files such as ${context.generatedFiles.map((file) => `\`${file}\``).join(", ")}.
+If generated output is stale or broken, update the owning source file and run \`akan repair generated\` or \`akan sync <app-or-lib>\`.
+
+## MCP Workflow Policy
+
+- Prefer Akan MCP workflows before direct source edits.
+- Direct source edits are denied when an allowlisted Akan workflow or repair tool can perform the change.
+- Use \`akan mcp --mode plan\` to inspect \`list_workflows\`, \`explain_workflow\`, and \`plan_workflow\`.
+- If \`plan_workflow\` returns \`planPath\` or \`next.tool=apply_workflow\`, call \`apply_workflow({ planPath })\` before editing source files directly.
+- Use \`akan mcp --mode apply\` only for allowlisted \`apply_workflow\`, \`run_validation\`, and repair tools.
+- After \`apply_workflow\`, run \`run_validation\` with \`validationTarget\` when present; otherwise use \`applyReportPath\`.
+- If no workflow exists, or apply reports unsupported/no-op/failed diagnostics that require manual action, keep edits scoped to owning source files and never patch generated files directly.
+- For compound requests, split the request into workflows and apply each \`planPath\` in order, such as \`create-module\` followed by \`add-field\`.
+- **CLI-only fallback (MCP not connected):** \`akan mcp\` starts a stdio MCP server, so the \`list_workflows\`/\`plan_workflow\`/\`apply_workflow\` tools exist only when your agent is wired to it as an MCP client. When they are unavailable, the CLI is a first-class equivalent: \`akan workflow list\` / \`explain <name>\` / \`plan <name> ... --format json --out <planPath>\` / \`apply <planPath> --format json\`, \`akan doctor --strict --format json\` for validation, and \`akan repair generated|imports|module-shape --app <app> --format json\` for repairs. Scaffolding primitives (\`create-module\`/\`create-scalar\`/\`create-service\` take the target app/lib as a POSITIONAL arg; \`add-field\`/\`add-enum-field\` use \`--app\`/\`--module\` flags) call the same code the workflows do.
+
+## Validation
+
+${context.validationCommands.map((command) => `- \`${command}\``).join(`
+`)}
+
+## Framework Guide
+
+${frameworkGuide.trim()}`;
+};
+var upsertManagedBlock = (existing, block) => {
+  const managed = `${AGENT_BLOCK_START}
+${block}
+${AGENT_BLOCK_END}`;
+  const startIndex = existing.indexOf(AGENT_BLOCK_START);
+  const endIndex = existing.indexOf(AGENT_BLOCK_END);
+  if (startIndex >= 0 && endIndex > startIndex) {
+    return `${existing.slice(0, startIndex)}${managed}${existing.slice(endIndex + AGENT_BLOCK_END.length)}`;
+  }
+  return `${existing.replace(/\s*$/, "")}
+
+${managed}
+`;
+};
+var renderAgentsMd = async (workspace, existing) => {
+  const block = await renderManagedBlock(workspace);
+  if (existing?.trim())
+    return upsertManagedBlock(existing, block);
+  const context = await AkanContextAnalyzer.analyze(workspace);
+  return `# ${context.repoName} Agent Guide
+
+This file is the single source of truth for coding agents in this workspace. Claude Code reads it through
+\`CLAUDE.md\` (\`@AGENTS.md\`) and Cursor through \`.cursor/rules/akan.mdc\`. The section between the
+\`akan:agent\` markers is regenerated by \`akan agent install\`; edit anything outside the markers freely.
+
+${AGENT_BLOCK_START}
+${block}
+${AGENT_BLOCK_END}
+`;
+};
+var renderClaudeMd = async (workspace) => {
+  const context = await AkanContextAnalyzer.analyze(workspace);
+  return `# ${context.repoName} \u2014 Claude Code Guide
+
+@AGENTS.md
+`;
+};
+var renderCursorRule = () => `---
+description: Akan workspace agent guide
+alwaysApply: true
+---
+
+Follow the workspace agent guide, which is the single source of truth for Akan conventions,
+generated-file rules, and the MCP workflow policy.
+
+@AGENTS.md
+`;
+var renderTarget = async (workspace, target, existing) => {
+  if (target === "agents-md")
+    return await renderAgentsMd(workspace, existing);
+  if (target === "claude")
+    return await renderClaudeMd(workspace);
+  return renderCursorRule();
+};
+
+class AgentRunner extends runner("agent") {
+  async install(workspace, targets, { force = false } = {}) {
+    const written = [];
+    for (const target of targets) {
+      const filePath = targetPaths[target];
+      const exists = await workspace.exists(filePath);
+      if (exists && !force && target !== "agents-md") {
+        throw new Error(`${filePath} already exists. Re-run with --force to overwrite it.`);
+      }
+      const existing = exists ? await workspace.readFile(filePath) : null;
+      const content = await renderTarget(workspace, target, existing);
+      await workspace.writeFile(filePath, content, { overwrite: true });
+      written.push(filePath);
+    }
+    return written;
+  }
+}
+
+// pkgs/@akanjs/cli/agent/agent.script.ts
+var resolveTargets = (target) => {
+  if (!target || target === "all")
+    return ["cursor", "agents-md", "claude"];
+  if (target === "cursor" || target === "agents-md" || target === "claude")
+    return [target];
+  throw new Error(`Unknown agent target: ${target}. Use cursor, agents-md, claude, or all.`);
+};
+
+class AgentScript extends script("agent", [AgentRunner]) {
+  async agent(workspace, action, target, { force = false } = {}) {
+    if (action !== "install")
+      throw new Error(`Unknown agent action: ${action}. Use "install".`);
+    const written = await this.agentRunner.install(workspace, resolveTargets(target), { force });
+    Logger.rawLog(`Agent rules written:
+${written.map((file) => `- ${file}`).join(`
+`)}`);
+  }
+}
+
+export { AgentScript };

package/index-pmm9e2jf.js

@@ -0,0 +1,120 @@
+// @bun
+import {
+  runner,
+  script
+} from "./index-hdqztm58.js";
+import {
+  LibExecutor
+} from "./index-a6sbyy0b.js";
+
+// pkgs/@akanjs/cli/semver.ts
+function parseVersion(version) {
+  return version.replace(/^[^\d]*/, "").split(/[.-]/).map((part) => Number.parseInt(part, 10)).map((part) => Number.isFinite(part) ? part : 0);
+}
+function compareSemver(a, b) {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  const length = Math.max(left.length, right.length);
+  for (let i = 0;i < length; i++) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0);
+    if (diff !== 0)
+      return diff > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+// pkgs/@akanjs/cli/library/library.runner.ts
+class LibraryRunner extends runner("library") {
+  async createLibrary(libName, workspace) {
+    await workspace.exec(`mkdir -p libs/${libName}`);
+    await workspace.applyTemplate({ basePath: `libs/${libName}`, template: "libRoot", dict: { libName } });
+    const lib = LibExecutor.from(workspace, libName);
+    return lib;
+  }
+  async removeLibrary(lib) {
+    await lib.workspace.exec(`rm -rf libs/${lib.name}`);
+  }
+  async#copyInstalledLibrary(workspace, libName) {
+    const installedPackageJson = `node_modules/akanjs/libs/${libName}/package.json`;
+    if (!await workspace.exists(installedPackageJson))
+      return false;
+    await workspace.cp(`node_modules/akanjs/libs/${libName}`, `libs/${libName}`);
+    return true;
+  }
+  async#copyLibraryFromRepository(workspace, libName) {
+    await workspace.mkdir("node_modules/.akan");
+    if (await workspace.exists("node_modules/.akan/akanjs"))
+      await workspace.removeDir("node_modules/.akan/akanjs");
+    await workspace.exec(`cd node_modules/.akan && git clone https://github.com/akan-team/akanjs.git`);
+    await workspace.cp(`node_modules/.akan/akanjs/libs/${libName}`, `libs/${libName}`);
+  }
+  async installLibrary(workspace, libName) {
+    const copiedFromInstalledPackage = await this.#copyInstalledLibrary(workspace, libName);
+    if (!copiedFromInstalledPackage)
+      await this.#copyLibraryFromRepository(workspace, libName);
+    await workspace.cp(`libs/${libName}/env/env.server.example.ts`, `libs/${libName}/env/env.server.testing.ts`);
+    await workspace.commit(`Add ${libName} library`);
+    return LibExecutor.from(workspace, libName);
+  }
+  async mergeLibraryDependencies(lib) {
+    const libPackageJson = await lib.getPackageJson();
+    const rootPackageJson = await lib.workspace.getPackageJson();
+    const dependencies = {};
+    const devDependencies = {};
+    const libDependencies = { ...libPackageJson.dependencies, ...libPackageJson.devDependencies };
+    const rootDependencies = { ...rootPackageJson.dependencies, ...rootPackageJson.devDependencies };
+    const allDependencies = Object.fromEntries(Object.keys({ ...libDependencies, ...rootDependencies }).map((dep) => {
+      const libVersion = libDependencies[dep] ?? "0.0.0";
+      const rootVersion = rootDependencies[dep] ?? "0.0.0";
+      const newerVersion = compareSemver(rootVersion, libVersion) > 0 ? rootVersion : libVersion;
+      return [dep, newerVersion];
+    }));
+    Object.keys(allDependencies).sort().forEach((dep) => {
+      if (!!libPackageJson.dependencies?.[dep] || !!rootPackageJson.dependencies?.[dep])
+        dependencies[dep] = allDependencies[dep];
+      else
+        devDependencies[dep] = allDependencies[dep];
+    });
+    const newRootPackageJson = { ...rootPackageJson, dependencies, devDependencies };
+    await lib.workspace.setPackageJson(newRootPackageJson);
+    await lib.workspace.spawn("bun", ["install"]);
+    await lib.workspace.commit(`Merge ${lib.name} library dependencies`);
+  }
+  async testLibrary(lib) {}
+}
+
+// pkgs/@akanjs/cli/library/library.script.ts
+class LibraryScript extends script("library", [LibraryRunner]) {
+  async syncLibrary(lib) {
+    const syncSpinner = lib.spinning("Syncing library...");
+    const scanInfo = await lib.scan();
+    syncSpinner.succeed(`Library ${lib.name} (libs/${lib.name}) is synced`);
+    return scanInfo;
+  }
+  async createLibrary(libName, workspace) {
+    const spinner = workspace.spinning(`Creating ${libName} library`);
+    const lib = await this.libraryRunner.createLibrary(libName, workspace);
+    spinner.succeed(`${libName} library (libs/${libName}) is created`);
+    await this.syncLibrary(lib);
+  }
+  async removeLibrary(lib) {
+    const spinner = lib.spinning("Removing library...");
+    await this.libraryRunner.removeLibrary(lib);
+    spinner.succeed(`Library ${lib.name} (libs/${lib.name}) is removed`);
+  }
+  async installLibrary(workspace, libName) {
+    const installSpinner = workspace.spinning(`Installing ${libName} library`);
+    const lib = await this.libraryRunner.installLibrary(workspace, libName);
+    installSpinner.succeed(`${libName} library (libs/${libName}) is installed`);
+    const mergeSpinner = lib.spinning("Merging library dependencies...");
+    await this.libraryRunner.mergeLibraryDependencies(lib);
+    mergeSpinner.succeed(`${libName} library (libs/${libName}) dependencies merged to root package.json`);
+  }
+  async testLibrary(lib) {
+    const spinner = lib.spinning("Testing library...");
+    await this.libraryRunner.testLibrary(lib);
+    spinner.succeed(`Library ${lib.name} (libs/${lib.name}) test is successful`);
+  }
+}
+
+export { LibraryScript };

package/index-qaq13qk3.js

@@ -0,0 +1,80 @@
+// @bun
+import {
+  getDirname
+} from "./index-a6sbyy0b.js";
+
+// pkgs/@akanjs/devkit/prompter.ts
+import fsPromise from "fs/promises";
+import { input, select } from "@inquirer/prompts";
+class Prompter {
+  static async#getGuidelineRoot() {
+    const dirname = getDirname(import.meta.url);
+    const candidates = [`${dirname}/guidelines`, `${dirname}/../cli/guidelines`];
+    for (const candidate of candidates) {
+      try {
+        await fsPromise.access(candidate);
+        return candidate;
+      } catch {}
+    }
+    return candidates[0];
+  }
+  static async selectGuideline() {
+    const guidelineRoot = await Prompter.#getGuidelineRoot();
+    const guideNames = await Prompter.listGuidelines();
+    return await select({
+      message: "Select a guideline",
+      choices: guideNames.map((name) => ({ name, value: name }))
+    });
+  }
+  static async listGuidelines() {
+    const guidelineRoot = await Prompter.#getGuidelineRoot();
+    return (await fsPromise.readdir(guidelineRoot)).filter((name) => !name.startsWith("_")).sort();
+  }
+  static async getGuideJson(guideName) {
+    const guidelineRoot = await Prompter.#getGuidelineRoot();
+    const filePath = `${guidelineRoot}/${guideName}/${guideName}.generate.json`;
+    const guideJson = await fsPromise.readFile(filePath, "utf-8");
+    return JSON.parse(guideJson);
+  }
+  static async getInstruction(guideName) {
+    const guidelineRoot = await Prompter.#getGuidelineRoot();
+    const filePath = `${guidelineRoot}/${guideName}/${guideName}.instruction.md`;
+    const content = await fsPromise.readFile(filePath, "utf-8");
+    return content;
+  }
+  static async getUpdateRequest(guideName) {
+    return await input({
+      message: `What do you want to update in ${guideName}?`
+    });
+  }
+  async makeTsFileUpdatePrompt({ context, request }) {
+    return `You are a senior developer writing TypeScript-based programs using Akan.js, an in-house framework. Here's an overview of the Akan.js framework:
+${await this.getDocumentation("framework")}
+Please understand the following background information, write code that meets the requirements, verify that it satisfies the validation conditions, and return the result.
+
+# Code Style
+- Use double quotes for all string literals in TypeScript/TSX code. Do not use single quotes.
+
+# Background Information
+\`\`\`markdown
+${context}
+\`\`\`
+
+# Requirements
+\`\`\`markdown
+${request}
+\`\`\`
+`;
+  }
+  async getDocumentation(guideName) {
+    const guidelineRoot = await Prompter.#getGuidelineRoot();
+    const filePath = `${guidelineRoot}/${guideName}/${guideName}.instruction.md`;
+    const document = await fsPromise.readFile(filePath, "utf-8");
+    return `\`\`\`markdown
+${document}
+\`\`\`
+`;
+  }
+}
+
+export { Prompter };