planmode 0.1.0

package/src/lib/manifest.ts

@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "yaml";
+import type { PackageManifest, PackageType, VariableType, Category } from "../types/index.js";
+
+const NAME_REGEX = /^(@[a-z0-9-]+\/)?[a-z0-9][a-z0-9-]*$/;
+const SEMVER_REGEX = /^\d+\.\d+\.\d+$/;
+const VALID_TYPES: PackageType[] = ["prompt", "rule", "plan"];
+const VALID_VAR_TYPES: VariableType[] = ["string", "number", "boolean", "enum", "resolved"];
+const VALID_CATEGORIES: Category[] = [
+  "frontend", "backend", "devops", "database", "testing",
+  "mobile", "ai-ml", "design", "security", "other",
+];
+
+export function parseManifest(raw: string): PackageManifest {
+  const data = parse(raw);
+  if (!data || typeof data !== "object") {
+    throw new Error("Invalid YAML: manifest must be an object");
+  }
+  return data as PackageManifest;
+}
+
+export function readManifest(dir: string): PackageManifest {
+  const manifestPath = path.join(dir, "planmode.yaml");
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`No planmode.yaml found in ${dir}`);
+  }
+  const raw = fs.readFileSync(manifestPath, "utf-8");
+  return parseManifest(raw);
+}
+
+export function validateManifest(manifest: PackageManifest, requirePublishFields = false): string[] {
+  const errors: string[] = [];
+
+  // Required fields
+  if (!manifest.name) {
+    errors.push("Missing required field: name");
+  } else if (!NAME_REGEX.test(manifest.name)) {
+    errors.push(`Invalid name "${manifest.name}": must match ${NAME_REGEX}`);
+  } else if (manifest.name.length > 100) {
+    errors.push("Name must be 100 characters or fewer");
+  }
+
+  if (!manifest.version) {
+    errors.push("Missing required field: version");
+  } else if (!SEMVER_REGEX.test(manifest.version)) {
+    errors.push(`Invalid version "${manifest.version}": must be valid semver (X.Y.Z)`);
+  }
+
+  if (!manifest.type) {
+    errors.push("Missing required field: type");
+  } else if (!VALID_TYPES.includes(manifest.type)) {
+    errors.push(`Invalid type "${manifest.type}": must be one of ${VALID_TYPES.join(", ")}`);
+  }
+
+  // Publish fields
+  if (requirePublishFields) {
+    if (!manifest.description) errors.push("Missing required field: description");
+    if (manifest.description && manifest.description.length > 200) {
+      errors.push("Description must be 200 characters or fewer");
+    }
+    if (!manifest.author) errors.push("Missing required field: author");
+    if (!manifest.license) errors.push("Missing required field: license");
+  }
+
+  // Optional field validation
+  if (manifest.tags) {
+    if (manifest.tags.length > 10) {
+      errors.push("Maximum 10 tags allowed");
+    }
+    for (const tag of manifest.tags) {
+      if (!/^[a-z0-9][a-z0-9-]*$/.test(tag)) {
+        errors.push(`Invalid tag "${tag}": must be lowercase alphanumeric with hyphens`);
+      }
+    }
+  }
+
+  if (manifest.category && !VALID_CATEGORIES.includes(manifest.category)) {
+    errors.push(`Invalid category "${manifest.category}": must be one of ${VALID_CATEGORIES.join(", ")}`);
+  }
+
+  // Dependencies only for plan and rule
+  if (manifest.dependencies && manifest.type === "prompt") {
+    errors.push("Dependencies are not allowed for prompt type packages");
+  }
+
+  // Variable validation
+  if (manifest.variables) {
+    for (const [varName, varDef] of Object.entries(manifest.variables)) {
+      if (!varDef.type || !VALID_VAR_TYPES.includes(varDef.type)) {
+        errors.push(`Variable "${varName}" has invalid type: must be one of ${VALID_VAR_TYPES.join(", ")}`);
+      }
+      if (varDef.type === "enum" && (!varDef.options || varDef.options.length === 0)) {
+        errors.push(`Variable "${varName}" of type enum must have options`);
+      }
+    }
+  }
+
+  // Content
+  if (manifest.content && manifest.content_file) {
+    errors.push("Cannot specify both content and content_file");
+  }
+
+  return errors;
+}
+
+export function readPackageContent(dir: string, manifest: PackageManifest): string {
+  if (manifest.content) {
+    return manifest.content;
+  }
+  if (manifest.content_file) {
+    const contentPath = path.join(dir, manifest.content_file);
+    if (!fs.existsSync(contentPath)) {
+      throw new Error(`Content file not found: ${manifest.content_file}`);
+    }
+    return fs.readFileSync(contentPath, "utf-8");
+  }
+  throw new Error("Package must specify either content or content_file");
+}

package/src/lib/registry.ts

@@ -0,0 +1,135 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getCacheDir, getCacheTTL, getRegistries, getGitHubToken } from "./config.js";
+import type { RegistryIndex, PackageSummary, PackageMetadata, VersionMetadata } from "../types/index.js";
+
+const INDEX_CACHE_FILE = "index.json";
+
+function getHeaders(): Record<string, string> {
+  const headers: Record<string, string> = {
+    "Accept": "application/vnd.github.v3.raw+json",
+    "User-Agent": "planmode-cli",
+  };
+  const token = getGitHubToken();
+  if (token) {
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+  return headers;
+}
+
+function registryRawUrl(registryUrl: string, filePath: string): string {
+  // Convert github.com/org/repo to raw.githubusercontent.com URL
+  const match = registryUrl.match(/^github\.com\/([^/]+)\/([^/]+)$/);
+  if (!match) {
+    throw new Error(`Invalid registry URL: ${registryUrl}`);
+  }
+  return `https://raw.githubusercontent.com/${match[1]}/${match[2]}/main/${filePath}`;
+}
+
+function resolveRegistry(packageName: string): string {
+  const registries = getRegistries();
+
+  // Scoped packages: @scope/name → look up scope in registries
+  if (packageName.startsWith("@")) {
+    const scope = packageName.split("/")[0]!.slice(1);
+    const registryUrl = registries[scope];
+    if (!registryUrl) {
+      throw new Error(
+        `No registry configured for scope "@${scope}". Run: planmode registry add ${scope} <url>`,
+      );
+    }
+    return registryUrl;
+  }
+
+  return registries["default"]!;
+}
+
+export async function fetchIndex(registryUrl?: string): Promise<RegistryIndex> {
+  const url = registryUrl ?? getRegistries()["default"]!;
+  const cacheDir = getCacheDir();
+  const cachePath = path.join(cacheDir, INDEX_CACHE_FILE);
+  const ttl = getCacheTTL();
+
+  // Check cache
+  try {
+    const stat = fs.statSync(cachePath);
+    const ageSeconds = (Date.now() - stat.mtimeMs) / 1000;
+    if (ageSeconds < ttl) {
+      const cached = JSON.parse(fs.readFileSync(cachePath, "utf-8"));
+      return cached as RegistryIndex;
+    }
+  } catch {
+    // Cache miss
+  }
+
+  // Fetch from remote
+  const rawUrl = registryRawUrl(url, "index.json");
+  const response = await fetch(rawUrl, { headers: getHeaders() });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch registry index: ${response.status} ${response.statusText}`);
+  }
+  const data = (await response.json()) as RegistryIndex;
+
+  // Write cache
+  fs.mkdirSync(cacheDir, { recursive: true });
+  fs.writeFileSync(cachePath, JSON.stringify(data, null, 2), "utf-8");
+
+  return data;
+}
+
+export async function searchPackages(
+  query: string,
+  options?: { type?: string; category?: string },
+): Promise<PackageSummary[]> {
+  const index = await fetchIndex();
+  const q = query.toLowerCase();
+
+  let results = index.packages.filter((pkg) => {
+    const searchable = [pkg.name, pkg.description, pkg.author, ...pkg.tags].join(" ").toLowerCase();
+    return searchable.includes(q);
+  });
+
+  if (options?.type) {
+    results = results.filter((pkg) => pkg.type === options.type);
+  }
+  if (options?.category) {
+    results = results.filter((pkg) => pkg.category === options.category);
+  }
+
+  return results.sort((a, b) => b.downloads - a.downloads);
+}
+
+export async function fetchPackageMetadata(packageName: string): Promise<PackageMetadata> {
+  const registryUrl = resolveRegistry(packageName);
+  const name = packageName.startsWith("@") ? packageName.split("/")[1]! : packageName;
+  const rawUrl = registryRawUrl(registryUrl, `packages/${name}/metadata.json`);
+
+  const response = await fetch(rawUrl, { headers: getHeaders() });
+  if (!response.ok) {
+    if (response.status === 404) {
+      throw new Error(
+        `Package '${packageName}' not found in registry. Run \`planmode search <query>\` to find packages.`,
+      );
+    }
+    throw new Error(`Failed to fetch package metadata: ${response.status}`);
+  }
+  return (await response.json()) as PackageMetadata;
+}
+
+export async function fetchVersionMetadata(
+  packageName: string,
+  version: string,
+): Promise<VersionMetadata> {
+  const registryUrl = resolveRegistry(packageName);
+  const name = packageName.startsWith("@") ? packageName.split("/")[1]! : packageName;
+  const rawUrl = registryRawUrl(registryUrl, `packages/${name}/versions/${version}.json`);
+
+  const response = await fetch(rawUrl, { headers: getHeaders() });
+  if (!response.ok) {
+    if (response.status === 404) {
+      throw new Error(`Version '${version}' not found for '${packageName}'.`);
+    }
+    throw new Error(`Failed to fetch version metadata: ${response.status}`);
+  }
+  return (await response.json()) as VersionMetadata;
+}

package/src/lib/resolver.ts

@@ -0,0 +1,120 @@
+import type { PackageMetadata } from "../types/index.js";
+import { fetchPackageMetadata } from "./registry.js";
+
+interface VersionRange {
+  operator: "exact" | "caret" | "tilde" | "gte" | "any";
+  major: number;
+  minor: number;
+  patch: number;
+}
+
+function parseSemver(version: string): { major: number; minor: number; patch: number } {
+  const parts = version.split(".").map(Number);
+  return { major: parts[0]!, minor: parts[1]!, patch: parts[2]! };
+}
+
+function parseVersionRange(range: string): VersionRange {
+  if (range === "*") {
+    return { operator: "any", major: 0, minor: 0, patch: 0 };
+  }
+  if (range.startsWith("^")) {
+    const { major, minor, patch } = parseSemver(range.slice(1));
+    return { operator: "caret", major, minor, patch };
+  }
+  if (range.startsWith("~")) {
+    const { major, minor, patch } = parseSemver(range.slice(1));
+    return { operator: "tilde", major, minor, patch };
+  }
+  if (range.startsWith(">=")) {
+    const { major, minor, patch } = parseSemver(range.slice(2));
+    return { operator: "gte", major, minor, patch };
+  }
+  const { major, minor, patch } = parseSemver(range);
+  return { operator: "exact", major, minor, patch };
+}
+
+function satisfies(version: string, range: VersionRange): boolean {
+  const v = parseSemver(version);
+
+  switch (range.operator) {
+    case "any":
+      return true;
+
+    case "exact":
+      return v.major === range.major && v.minor === range.minor && v.patch === range.patch;
+
+    case "caret":
+      // ^1.2.3 → >=1.2.3, <2.0.0
+      if (v.major !== range.major) return false;
+      if (v.minor > range.minor) return true;
+      if (v.minor === range.minor) return v.patch >= range.patch;
+      return false;
+
+    case "tilde":
+      // ~1.2.3 → >=1.2.3, <1.3.0
+      if (v.major !== range.major) return false;
+      if (v.minor !== range.minor) return false;
+      return v.patch >= range.patch;
+
+    case "gte":
+      if (v.major > range.major) return true;
+      if (v.major < range.major) return false;
+      if (v.minor > range.minor) return true;
+      if (v.minor < range.minor) return false;
+      return v.patch >= range.patch;
+  }
+}
+
+function compareVersions(a: string, b: string): number {
+  const va = parseSemver(a);
+  const vb = parseSemver(b);
+  if (va.major !== vb.major) return va.major - vb.major;
+  if (va.minor !== vb.minor) return va.minor - vb.minor;
+  return va.patch - vb.patch;
+}
+
+export function parseDepString(dep: string): { name: string; range: string } {
+  const atIndex = dep.lastIndexOf("@");
+  if (atIndex > 0) {
+    return {
+      name: dep.slice(0, atIndex),
+      range: dep.slice(atIndex + 1),
+    };
+  }
+  return { name: dep, range: "*" };
+}
+
+export async function resolveVersion(
+  packageName: string,
+  versionRange?: string,
+): Promise<{ version: string; metadata: PackageMetadata }> {
+  const metadata = await fetchPackageMetadata(packageName);
+
+  if (!versionRange || versionRange === "latest") {
+    return { version: metadata.latest_version, metadata };
+  }
+
+  const range = parseVersionRange(versionRange);
+  const matching = metadata.versions
+    .filter((v) => satisfies(v, range))
+    .sort(compareVersions);
+
+  if (matching.length === 0) {
+    throw new Error(
+      `Version '${versionRange}' not found for '${packageName}'. Available: ${metadata.versions.join(", ")}`,
+    );
+  }
+
+  const version = matching[matching.length - 1]!;
+  return { version, metadata };
+}
+
+export function findHighestSatisfying(versions: string[], ranges: string[]): string | null {
+  const parsedRanges = ranges.map(parseVersionRange);
+
+  const matching = versions
+    .filter((v) => parsedRanges.every((range) => satisfies(v, range)))
+    .sort(compareVersions);
+
+  return matching.length > 0 ? matching[matching.length - 1]! : null;
+}

package/src/lib/template.ts

@@ -0,0 +1,110 @@
+import Handlebars from "handlebars";
+import type { VariableDefinition } from "../types/index.js";
+
+// Register helpers
+Handlebars.registerHelper("eq", (a, b) => a === b);
+
+export function renderTemplate(
+  content: string,
+  variables: Record<string, string | number | boolean>,
+): string {
+  const template = Handlebars.compile(content);
+  return template(variables);
+}
+
+export function collectVariableValues(
+  variableDefs: Record<string, VariableDefinition>,
+  provided: Record<string, string>,
+): Record<string, string | number | boolean> {
+  const values: Record<string, string | number | boolean> = {};
+
+  for (const [name, def] of Object.entries(variableDefs)) {
+    const rawValue = provided[name];
+
+    if (rawValue !== undefined) {
+      values[name] = coerceValue(rawValue, def);
+    } else if (def.default !== undefined) {
+      values[name] = def.default;
+    } else if (def.required) {
+      throw new Error(`Missing required variable: ${name} — ${def.description}`);
+    }
+  }
+
+  return values;
+}
+
+function coerceValue(
+  raw: string,
+  def: VariableDefinition,
+): string | number | boolean {
+  switch (def.type) {
+    case "number":
+      return Number(raw);
+    case "boolean":
+      return raw === "true" || raw === "1" || raw === "yes";
+    case "enum":
+      if (def.options && !def.options.includes(raw)) {
+        throw new Error(
+          `Invalid value "${raw}" for enum variable. Options: ${def.options.join(", ")}`,
+        );
+      }
+      return raw;
+    default:
+      return raw;
+  }
+}
+
+export async function resolveVariable(
+  def: VariableDefinition,
+  currentValues: Record<string, string | number | boolean>,
+): Promise<string> {
+  if (def.type !== "resolved" || !def.source) {
+    throw new Error("resolveVariable called on non-resolved variable");
+  }
+
+  // Render the source URL with current variable values
+  const sourceUrl = renderTemplate(def.source, currentValues);
+
+  const response = await fetch(sourceUrl);
+  if (!response.ok) {
+    throw new Error(`Failed to resolve variable from ${sourceUrl}: ${response.status}`);
+  }
+
+  const data = await response.json();
+
+  // Extract value using dot-bracket notation path
+  if (def.extract) {
+    return extractPath(data, def.extract);
+  }
+
+  return String(data);
+}
+
+function extractPath(obj: unknown, pathStr: string): string {
+  const parts = pathStr.match(/[^.[\]]+/g);
+  if (!parts) return String(obj);
+
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current === null || current === undefined) return "";
+    if (typeof current === "object") {
+      current = (current as Record<string, unknown>)[part];
+    }
+  }
+  return String(current ?? "");
+}
+
+export function getMissingRequiredVariables(
+  variableDefs: Record<string, VariableDefinition>,
+  provided: Record<string, string>,
+): Array<{ name: string; def: VariableDefinition }> {
+  const missing: Array<{ name: string; def: VariableDefinition }> = [];
+
+  for (const [name, def] of Object.entries(variableDefs)) {
+    if (def.required && provided[name] === undefined && def.default === undefined) {
+      missing.push({ name, def });
+    }
+  }
+
+  return missing;
+}

package/src/types/index.ts

@@ -0,0 +1,144 @@
+// ── Package manifest (planmode.yaml) ──
+
+export type PackageType = "prompt" | "rule" | "plan";
+export type VariableType = "string" | "number" | "boolean" | "enum" | "resolved";
+export type Category =
+  | "frontend"
+  | "backend"
+  | "devops"
+  | "database"
+  | "testing"
+  | "mobile"
+  | "ai-ml"
+  | "design"
+  | "security"
+  | "other";
+
+export interface VariableDefinition {
+  description: string;
+  type: VariableType;
+  options?: string[];
+  required?: boolean;
+  default?: string | number | boolean;
+  resolver?: string;
+  source?: string;
+  extract?: string;
+}
+
+export interface PackageManifest {
+  name: string;
+  version: string;
+  type: PackageType;
+  description: string;
+  author: string;
+  license: string;
+  repository?: string;
+  models?: string[];
+  tags?: string[];
+  category?: Category;
+  dependencies?: {
+    rules?: string[];
+    plans?: string[];
+  };
+  variables?: Record<string, VariableDefinition>;
+  content?: string;
+  content_file?: string;
+}
+
+// ── Registry ──
+
+export interface PackageSummary {
+  name: string;
+  version: string;
+  type: PackageType;
+  description: string;
+  author: string;
+  category: string;
+  tags: string[];
+  downloads: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface RegistryIndex {
+  version: number;
+  updated_at: string;
+  packages: PackageSummary[];
+}
+
+export interface PackageMetadata {
+  name: string;
+  description: string;
+  author: string;
+  license: string;
+  repository: string;
+  category: string;
+  tags: string[];
+  type: PackageType;
+  models: string[];
+  latest_version: string;
+  versions: string[];
+  downloads: number;
+  created_at: string;
+  updated_at: string;
+  dependencies?: {
+    rules?: string[];
+    plans?: string[];
+  };
+  variables?: Record<string, VariableDefinition>;
+}
+
+export interface VersionMetadata {
+  version: string;
+  published_at: string;
+  source: {
+    repository: string;
+    tag: string;
+    sha: string;
+  };
+  files: string[];
+  content_hash: string;
+}
+
+// ── Lockfile ──
+
+export interface LockfileEntry {
+  version: string;
+  type: PackageType;
+  source: string;
+  tag: string;
+  sha: string;
+  content_hash: string;
+  installed_to: string;
+}
+
+export interface Lockfile {
+  lockfile_version: number;
+  packages: Record<string, LockfileEntry>;
+}
+
+// ── Config ──
+
+export interface PlanmodeConfig {
+  auth?: {
+    github_token?: string;
+  };
+  registries?: Record<string, string>;
+  cache?: {
+    dir?: string;
+    ttl?: number;
+  };
+}
+
+// ── Resolved package info ──
+
+export interface ResolvedPackage {
+  name: string;
+  version: string;
+  source: string;
+  tag: string;
+  sha: string;
+  manifest: PackageManifest;
+  content: string;
+  contentHash: string;
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/tsup.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm"],
+  target: "node20",
+  outDir: "dist",
+  clean: true,
+  dts: true,
+  splitting: false,
+  banner: {
+    js: "#!/usr/bin/env node",
+  },
+});

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    include: ["tests/**/*.test.ts"],
+  },
+});