planmode 0.1.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "planmode",
+  "version": "0.1.0",
+  "description": "The open source package manager for AI plans, rules, and prompts.",
+  "type": "module",
+  "bin": {
+    "planmode": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "handlebars": "^4.7.8",
+    "simple-git": "^3.27.0",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kaihannonen/planmode.org"
+  },
+  "keywords": [
+    "planmode",
+    "ai",
+    "plans",
+    "prompts",
+    "rules",
+    "claude",
+    "package-manager"
+  ]
+}

package/src/commands/info.ts

@@ -0,0 +1,61 @@
+import { Command } from "commander";
+import { fetchPackageMetadata } from "../lib/registry.js";
+import { logger } from "../lib/logger.js";
+
+export const infoCommand = new Command("info")
+  .description("Show detailed info about a package")
+  .argument("<package>", "Package name")
+  .action(async (packageName: string) => {
+    try {
+      const meta = await fetchPackageMetadata(packageName);
+
+      logger.blank();
+      logger.bold(`${meta.name}@${meta.latest_version}`);
+      logger.blank();
+
+      console.log(`  Description:  ${meta.description}`);
+      console.log(`  Type:         ${meta.type}`);
+      console.log(`  Author:       ${meta.author}`);
+      console.log(`  License:      ${meta.license}`);
+      console.log(`  Category:     ${meta.category}`);
+      console.log(`  Downloads:    ${meta.downloads.toLocaleString()}`);
+      console.log(`  Repository:   ${meta.repository}`);
+
+      if (meta.models && meta.models.length > 0) {
+        console.log(`  Models:       ${meta.models.join(", ")}`);
+      }
+
+      if (meta.tags && meta.tags.length > 0) {
+        console.log(`  Tags:         ${meta.tags.join(", ")}`);
+      }
+
+      console.log(`  Versions:     ${meta.versions.join(", ")}`);
+
+      if (meta.dependencies) {
+        if (meta.dependencies.rules && meta.dependencies.rules.length > 0) {
+          console.log(`  Dep (rules):  ${meta.dependencies.rules.join(", ")}`);
+        }
+        if (meta.dependencies.plans && meta.dependencies.plans.length > 0) {
+          console.log(`  Dep (plans):  ${meta.dependencies.plans.join(", ")}`);
+        }
+      }
+
+      if (meta.variables) {
+        logger.blank();
+        logger.bold("  Variables:");
+        for (const [name, def] of Object.entries(meta.variables)) {
+          const required = def.required ? " (required)" : "";
+          const defaultVal = def.default !== undefined ? ` [default: ${def.default}]` : "";
+          console.log(`    ${name}: ${def.type}${required}${defaultVal} — ${def.description}`);
+          if (def.options) {
+            console.log(`      options: ${def.options.join(", ")}`);
+          }
+        }
+      }
+
+      logger.blank();
+    } catch (err) {
+      logger.error((err as Error).message);
+      process.exit(1);
+    }
+  });

package/src/commands/init.ts

@@ -0,0 +1,85 @@
+import { Command } from "commander";
+import fs from "node:fs";
+import path from "node:path";
+import { stringify } from "yaml";
+import { logger } from "../lib/logger.js";
+import type { PackageType, Category } from "../types/index.js";
+
+async function prompt(question: string): Promise<string> {
+  const { createInterface } = await import("node:readline");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+export const initCommand = new Command("init")
+  .description("Initialize a new package in the current directory")
+  .action(async () => {
+    try {
+      logger.blank();
+      logger.bold("Initialize a new Planmode package");
+      logger.blank();
+
+      const name = await prompt("Package name: ");
+      if (!name) {
+        logger.error("Package name is required.");
+        process.exit(1);
+      }
+
+      const typeInput = await prompt("Type (plan/rule/prompt) [plan]: ");
+      const type = (typeInput || "plan") as PackageType;
+
+      const description = await prompt("Description: ");
+      const author = await prompt("Author (GitHub username): ");
+      const license = await prompt("License [MIT]: ") || "MIT";
+      const tagsInput = await prompt("Tags (comma-separated): ");
+      const tags = tagsInput ? tagsInput.split(",").map((t) => t.trim().toLowerCase()) : [];
+      const category = (await prompt("Category (frontend/backend/devops/database/testing/mobile/ai-ml/security/other) [other]: ") || "other") as Category;
+
+      // Build manifest
+      const manifest: Record<string, unknown> = {
+        name,
+        version: "1.0.0",
+        type,
+        description,
+        author,
+        license,
+      };
+
+      if (tags.length > 0) manifest["tags"] = tags;
+      manifest["category"] = category;
+
+      const contentFile = `${type}.md`;
+      manifest["content_file"] = contentFile;
+
+      // Write planmode.yaml
+      const yamlContent = stringify(manifest);
+      fs.writeFileSync(path.join(process.cwd(), "planmode.yaml"), yamlContent, "utf-8");
+      logger.success("Created planmode.yaml");
+
+      // Write stub content file
+      const stubs: Record<string, string> = {
+        plan: `# ${name}\n\n1. First step\n2. Second step\n3. Third step\n`,
+        rule: `- Rule one\n- Rule two\n- Rule three\n`,
+        prompt: `Write your prompt here.\n\nUse {{variable_name}} for template variables.\n`,
+      };
+
+      fs.writeFileSync(
+        path.join(process.cwd(), contentFile),
+        stubs[type] ?? stubs["plan"]!,
+        "utf-8",
+      );
+      logger.success(`Created ${contentFile}`);
+
+      logger.blank();
+      logger.info(`Edit ${contentFile}, then run \`planmode publish\` when ready.`);
+      logger.blank();
+    } catch (err) {
+      logger.error((err as Error).message);
+      process.exit(1);
+    }
+  });

package/src/commands/install.ts

@@ -0,0 +1,29 @@
+import { Command } from "commander";
+import { installPackage } from "../lib/installer.js";
+import { logger } from "../lib/logger.js";
+
+export const installCommand = new Command("install")
+  .description("Install a package into the current project")
+  .argument("<package>", "Package name (e.g., nextjs-tailwind-starter)")
+  .option("-v, --version <version>", "Install specific version")
+  .option("--rule", "Force install as a rule to .claude/rules/")
+  .option("--no-input", "Fail if any required variable is missing")
+  .action(
+    async (
+      packageName: string,
+      options: { version?: string; rule?: boolean; input?: boolean },
+    ) => {
+      try {
+        logger.blank();
+        await installPackage(packageName, {
+          version: options.version,
+          forceRule: options.rule,
+          noInput: options.input === false,
+        });
+        logger.blank();
+      } catch (err) {
+        logger.error((err as Error).message);
+        process.exit(1);
+      }
+    },
+  );

package/src/commands/list.ts

@@ -0,0 +1,27 @@
+import { Command } from "commander";
+import { readLockfile } from "../lib/lockfile.js";
+import { logger } from "../lib/logger.js";
+
+export const listCommand = new Command("list")
+  .description("List all installed packages")
+  .action(() => {
+    const lockfile = readLockfile();
+    const entries = Object.entries(lockfile.packages);
+
+    if (entries.length === 0) {
+      logger.info("No packages installed. Run `planmode install <package>` to get started.");
+      return;
+    }
+
+    logger.blank();
+    logger.table(
+      ["name", "type", "version", "location"],
+      entries.map(([name, entry]) => [
+        name,
+        entry.type,
+        entry.version,
+        entry.installed_to,
+      ]),
+    );
+    logger.blank();
+  });

package/src/commands/login.ts

@@ -0,0 +1,56 @@
+import { Command } from "commander";
+import { execSync } from "node:child_process";
+import { setGitHubToken, getGitHubToken } from "../lib/config.js";
+import { logger } from "../lib/logger.js";
+
+export const loginCommand = new Command("login")
+  .description("Configure GitHub authentication")
+  .option("--token <token>", "GitHub personal access token")
+  .option("--gh", "Read token from GitHub CLI (gh auth token)")
+  .action(async (options: { token?: string; gh?: boolean }) => {
+    let token: string | undefined;
+
+    if (options.token) {
+      token = options.token;
+    } else if (options.gh) {
+      try {
+        token = execSync("gh auth token", { encoding: "utf-8" }).trim();
+      } catch {
+        logger.error("Failed to read token from GitHub CLI. Make sure `gh` is installed and authenticated.");
+        process.exit(1);
+      }
+    } else {
+      // Interactive prompt via stdin
+      const { createInterface } = await import("node:readline");
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      token = await new Promise<string>((resolve) => {
+        rl.question("GitHub personal access token: ", (answer) => {
+          rl.close();
+          resolve(answer.trim());
+        });
+      });
+    }
+
+    if (!token) {
+      logger.error("No token provided.");
+      process.exit(1);
+    }
+
+    // Validate token
+    logger.info("Validating token...");
+    const response = await fetch("https://api.github.com/user", {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "User-Agent": "planmode-cli",
+      },
+    });
+
+    if (!response.ok) {
+      logger.error("Invalid token. GitHub API returned: " + response.status);
+      process.exit(1);
+    }
+
+    const user = (await response.json()) as { login: string };
+    setGitHubToken(token);
+    logger.success(`Authenticated as ${user.login}`);
+  });

package/src/commands/publish.ts

@@ -0,0 +1,204 @@
+import { Command } from "commander";
+import { readManifest, validateManifest } from "../lib/manifest.js";
+import { getGitHubToken } from "../lib/config.js";
+import { getRemoteUrl, getHeadSha, createTag, pushTag } from "../lib/git.js";
+import { logger } from "../lib/logger.js";
+
+export const publishCommand = new Command("publish")
+  .description("Publish the current directory as a package to the registry")
+  .action(async () => {
+    try {
+      const cwd = process.cwd();
+
+      // Check auth
+      const token = getGitHubToken();
+      if (!token) {
+        logger.error("Not authenticated. Run `planmode login` first.");
+        process.exit(1);
+      }
+
+      // Read and validate manifest
+      logger.info("Reading planmode.yaml...");
+      const manifest = readManifest(cwd);
+      const errors = validateManifest(manifest, true);
+      if (errors.length > 0) {
+        logger.error("Invalid manifest:");
+        for (const err of errors) {
+          console.log(`  - ${err}`);
+        }
+        process.exit(1);
+      }
+
+      // Check git remote
+      const remoteUrl = await getRemoteUrl(cwd);
+      if (!remoteUrl) {
+        logger.error("No git remote found. Push your code to GitHub first.");
+        process.exit(1);
+      }
+
+      const sha = await getHeadSha(cwd);
+      const tag = `v${manifest.version}`;
+
+      // Create and push tag
+      logger.info(`Creating tag ${tag}...`);
+      try {
+        await createTag(cwd, tag);
+      } catch {
+        logger.dim(`Tag ${tag} already exists, using existing`);
+      }
+
+      try {
+        await pushTag(cwd, tag);
+        logger.success(`Pushed tag ${tag}`);
+      } catch {
+        logger.dim(`Tag ${tag} already pushed`);
+      }
+
+      // Fork registry and create PR via GitHub API
+      logger.info("Submitting to registry...");
+
+      const headers = {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/vnd.github.v3+json",
+        "User-Agent": "planmode-cli",
+        "Content-Type": "application/json",
+      };
+
+      // Fork the registry repo (idempotent)
+      await fetch("https://api.github.com/repos/planmode/registry/forks", {
+        method: "POST",
+        headers,
+      });
+
+      // Get authenticated user
+      const userRes = await fetch("https://api.github.com/user", { headers });
+      const user = (await userRes.json()) as { login: string };
+
+      // Create metadata files content
+      const metadataContent = JSON.stringify(
+        {
+          name: manifest.name,
+          description: manifest.description,
+          author: manifest.author,
+          license: manifest.license,
+          repository: remoteUrl
+            .replace(/^https?:\/\//, "")
+            .replace(/\.git$/, ""),
+          category: manifest.category ?? "other",
+          tags: manifest.tags ?? [],
+          type: manifest.type,
+          models: manifest.models ?? [],
+          latest_version: manifest.version,
+          versions: [manifest.version],
+          downloads: 0,
+          created_at: new Date().toISOString(),
+          updated_at: new Date().toISOString(),
+          dependencies: manifest.dependencies,
+          variables: manifest.variables,
+        },
+        null,
+        2,
+      );
+
+      const versionContent = JSON.stringify(
+        {
+          version: manifest.version,
+          published_at: new Date().toISOString(),
+          source: {
+            repository: remoteUrl
+              .replace(/^https?:\/\//, "")
+              .replace(/\.git$/, ""),
+            tag,
+            sha,
+          },
+          files: ["planmode.yaml", manifest.content_file ?? "inline"],
+          content_hash: `sha256:${sha.slice(0, 16)}`,
+        },
+        null,
+        2,
+      );
+
+      // Create branch on fork
+      const branchName = `add-${manifest.name}-${manifest.version}`;
+
+      // Get main branch ref
+      const refRes = await fetch(
+        `https://api.github.com/repos/${user.login}/registry/git/ref/heads/main`,
+        { headers },
+      );
+
+      if (!refRes.ok) {
+        logger.error("Failed to access registry fork. Make sure the fork exists.");
+        process.exit(1);
+      }
+
+      const refData = (await refRes.json()) as { object: { sha: string } };
+      const baseSha = refData.object.sha;
+
+      // Create branch
+      await fetch(`https://api.github.com/repos/${user.login}/registry/git/refs`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          ref: `refs/heads/${branchName}`,
+          sha: baseSha,
+        }),
+      });
+
+      // Create metadata.json
+      await fetch(
+        `https://api.github.com/repos/${user.login}/registry/contents/packages/${manifest.name}/metadata.json`,
+        {
+          method: "PUT",
+          headers,
+          body: JSON.stringify({
+            message: `Add ${manifest.name}@${manifest.version}`,
+            content: Buffer.from(metadataContent).toString("base64"),
+            branch: branchName,
+          }),
+        },
+      );
+
+      // Create version file
+      await fetch(
+        `https://api.github.com/repos/${user.login}/registry/contents/packages/${manifest.name}/versions/${manifest.version}.json`,
+        {
+          method: "PUT",
+          headers,
+          body: JSON.stringify({
+            message: `Add ${manifest.name}@${manifest.version} version metadata`,
+            content: Buffer.from(versionContent).toString("base64"),
+            branch: branchName,
+          }),
+        },
+      );
+
+      // Create PR
+      const prRes = await fetch("https://api.github.com/repos/planmode/registry/pulls", {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          title: `Add ${manifest.name}@${manifest.version}`,
+          head: `${user.login}:${branchName}`,
+          base: "main",
+          body: `## New package: ${manifest.name}\n\n- **Type:** ${manifest.type}\n- **Version:** ${manifest.version}\n- **Description:** ${manifest.description}\n- **Author:** ${manifest.author}\n\nSubmitted via \`planmode publish\`.`,
+        }),
+      });
+
+      if (prRes.ok) {
+        const pr = (await prRes.json()) as { html_url: string };
+        logger.blank();
+        logger.success(`Published ${manifest.name}@${manifest.version}`);
+        logger.info(`PR: ${pr.html_url}`);
+      } else {
+        const err = await prRes.text();
+        logger.error(`Failed to create PR: ${err}`);
+        process.exit(1);
+      }
+
+      logger.blank();
+    } catch (err) {
+      logger.error((err as Error).message);
+      process.exit(1);
+    }
+  });

package/src/commands/run.ts

@@ -0,0 +1,87 @@
+import { Command } from "commander";
+import fs from "node:fs";
+import path from "node:path";
+import { parseManifest, readPackageContent } from "../lib/manifest.js";
+import { renderTemplate, collectVariableValues, resolveVariable } from "../lib/template.js";
+import { logger } from "../lib/logger.js";
+
+export const runCommand = new Command("run")
+  .description("Run a templated prompt and output to stdout")
+  .argument("<prompt>", "Prompt package name")
+  .option("--no-input", "Fail if any required variable is missing")
+  .option("--json", "Output as JSON")
+  .allowUnknownOption(true)
+  .action(async (promptName: string, options: { input?: boolean; json?: boolean }, cmd: Command) => {
+    try {
+      // Parse dynamic --var flags from raw args
+      const vars: Record<string, string> = {};
+      const rawArgs = cmd.args.slice(0);
+      for (let i = 0; i < rawArgs.length; i++) {
+        const arg = rawArgs[i]!;
+        if (arg.startsWith("--") && arg !== "--no-input" && arg !== "--json") {
+          const key = arg.slice(2);
+          const value = rawArgs[i + 1];
+          if (value && !value.startsWith("--")) {
+            vars[key] = value;
+            i++;
+          }
+        }
+      }
+
+      // Look for prompt locally first
+      const localPath = path.join(process.cwd(), "prompts", `${promptName}.md`);
+      const localManifestPath = path.join(process.cwd(), "prompts", promptName, "planmode.yaml");
+
+      let content: string;
+      let manifest: ReturnType<typeof parseManifest> | undefined;
+
+      if (fs.existsSync(localManifestPath)) {
+        const raw = fs.readFileSync(localManifestPath, "utf-8");
+        manifest = parseManifest(raw);
+        const dir = path.join(process.cwd(), "prompts", promptName);
+        content = readPackageContent(dir, manifest);
+      } else if (fs.existsSync(localPath)) {
+        content = fs.readFileSync(localPath, "utf-8");
+      } else {
+        logger.error(`Prompt '${promptName}' not found locally. Install it first: planmode install ${promptName}`);
+        process.exit(1);
+      }
+
+      // Resolve variables
+      if (manifest?.variables && Object.keys(manifest.variables).length > 0) {
+        const values: Record<string, string | number | boolean> = {};
+
+        // First pass: resolve non-resolved variables
+        for (const [name, def] of Object.entries(manifest.variables)) {
+          if (def.type === "resolved") continue;
+          if (vars[name] !== undefined) {
+            values[name] = vars[name]!;
+          } else if (def.default !== undefined) {
+            values[name] = def.default;
+          } else if (def.required && options.input === false) {
+            logger.error(`Missing required variable: --${name}`);
+            process.exit(1);
+          }
+        }
+
+        // Second pass: resolve dynamic variables
+        for (const [name, def] of Object.entries(manifest.variables)) {
+          if (def.type !== "resolved") continue;
+          values[name] = await resolveVariable(def, values);
+        }
+
+        content = renderTemplate(content, values);
+
+        if (options.json) {
+          console.log(JSON.stringify({ rendered: content, variables: values }, null, 2));
+          return;
+        }
+      }
+
+      // Output rendered content
+      process.stdout.write(content);
+    } catch (err) {
+      logger.error((err as Error).message);
+      process.exit(1);
+    }
+  });

package/src/commands/search.ts

@@ -0,0 +1,45 @@
+import { Command } from "commander";
+import { searchPackages } from "../lib/registry.js";
+import { logger } from "../lib/logger.js";
+
+export const searchCommand = new Command("search")
+  .description("Search the registry for packages")
+  .argument("<query>", "Search query")
+  .option("--type <type>", "Filter by type (prompt, rule, plan)")
+  .option("--category <category>", "Filter by category")
+  .option("--json", "Output as JSON")
+  .action(async (query: string, options: { type?: string; category?: string; json?: boolean }) => {
+    try {
+      const results = await searchPackages(query, {
+        type: options.type,
+        category: options.category,
+      });
+
+      if (results.length === 0) {
+        logger.info("No packages found matching your query.");
+        return;
+      }
+
+      if (options.json) {
+        console.log(JSON.stringify(results, null, 2));
+        return;
+      }
+
+      logger.blank();
+      logger.table(
+        ["name", "type", "version", "description"],
+        results.map((pkg) => [
+          pkg.name,
+          pkg.type,
+          pkg.version,
+          pkg.description.length > 50
+            ? pkg.description.slice(0, 50) + "..."
+            : pkg.description,
+        ]),
+      );
+      logger.blank();
+    } catch (err) {
+      logger.error((err as Error).message);
+      process.exit(1);
+    }
+  });

package/src/commands/uninstall.ts

@@ -0,0 +1,17 @@
+import { Command } from "commander";
+import { uninstallPackage } from "../lib/installer.js";
+import { logger } from "../lib/logger.js";
+
+export const uninstallCommand = new Command("uninstall")
+  .description("Remove an installed package")
+  .argument("<package>", "Package name")
+  .action(async (packageName: string) => {
+    try {
+      logger.blank();
+      await uninstallPackage(packageName);
+      logger.blank();
+    } catch (err) {
+      logger.error((err as Error).message);
+      process.exit(1);
+    }
+  });