supipowers 2.1.0 → 2.2.0

package/src/context/rule-renderer.ts

@@ -1,7 +1,12 @@
-import type { RuleMode, WriteRuleAction } from "./startup-optimizer.js";
+import type { RuleMode, WriteCommandAction, WriteExtensionAction, WriteRuleAction } from "./startup-optimizer.js";
 
 export const MANAGED_RULE_HEADER = "<!-- supipowers:managed-rule";
 export const MANAGED_RULE_END = "-->";
+export const MANAGED_COMMAND_HEADER = "<!-- supipowers:managed-command";
+const MANAGED_COMMAND_FRONTMATTER_KEY = "supipowers-managed-command";
+const MANAGED_COMMAND_FRONTMATTER_VERSION = "1";
+export const MANAGED_EXTENSION_HEADER = "/* supipowers:managed-extension";
+export const MANAGED_EXTENSION_END = "*/";
 
 export interface ManagedRuleMetadata {
   version: number;
@@ -13,6 +18,26 @@ export interface ManagedRuleMetadata {
   sourceBytes: number;
 }
 
+export interface ManagedCommandMetadata {
+  version: number;
+  sourceId: string;
+  sourceName: string;
+  sourceHash: string;
+  slug: string;
+  commandName: string;
+  sourceBytes: number;
+}
+
+export interface ManagedExtensionMetadata {
+  version: number;
+  sourceId: string;
+  sourceName: string;
+  sourceHash: string;
+  slug: string;
+  extensionName: string;
+  sourceBytes: number;
+}
+
 export type ParsedManagedRule =
   | { status: "unmanaged"; managed: false }
   | {
@@ -29,6 +54,27 @@ export type ParsedManagedRule =
     }
   | { status: "malformed"; managed: true; error: string };
 
+export type ParsedManagedCommand =
+  | { status: "unmanaged"; managed: false }
+  | {
+      status: "managed";
+      managed: true;
+      metadata: ManagedCommandMetadata;
+      frontmatter: Record<string, string>;
+      body: string;
+    }
+  | { status: "malformed"; managed: true; error: string };
+
+export type ParsedManagedExtension =
+  | { status: "unmanaged"; managed: false }
+  | {
+      status: "managed";
+      managed: true;
+      metadata: ManagedExtensionMetadata;
+      body: string;
+    }
+  | { status: "malformed"; managed: true; error: string };
+
 /**
  * Render a managed rule file.
  *
@@ -56,6 +102,47 @@ export function renderManagedRule(action: WriteRuleAction): string {
   return `${metadata}\n---\n${frontmatter}\n---\n${body}`;
 }
 
+export function renderManagedCommand(action: WriteCommandAction): string {
+  const description = action.description ?? `Run ${action.sourceName} on demand.`;
+  const body = action.sourceContent.endsWith("\n")
+    ? action.sourceContent
+    : `${action.sourceContent}\n`;
+
+  return [
+    "---",
+    `description: ${frontmatterScalarLiteral(description)}`,
+    `${MANAGED_COMMAND_FRONTMATTER_KEY}: ${frontmatterScalarLiteral(MANAGED_COMMAND_FRONTMATTER_VERSION)}`,
+    `sourceId: ${frontmatterScalarLiteral(action.sourceId)}`,
+    `sourceName: ${frontmatterScalarLiteral(action.sourceName)}`,
+    `sourceHash: ${frontmatterScalarLiteral(action.sourceHash)}`,
+    `slug: ${frontmatterScalarLiteral(action.slug)}`,
+    `commandName: ${frontmatterScalarLiteral(action.commandName)}`,
+    `sourceBytes: ${action.sourceBytes}`,
+    "---",
+    body,
+  ].join("\n");
+}
+
+export function renderManagedExtension(action: WriteExtensionAction): string {
+  const metadata = [
+    MANAGED_EXTENSION_HEADER,
+    "version: 1",
+    `sourceId: ${action.sourceId}`,
+    `sourceName: ${action.sourceName}`,
+    `sourceHash: ${action.sourceHash}`,
+    `slug: ${action.slug}`,
+    `extensionName: ${action.extensionName}`,
+    `sourceBytes: ${action.sourceBytes}`,
+    MANAGED_EXTENSION_END,
+  ].join("\n");
+  const body = action.sourceContent.endsWith("\n")
+    ? action.sourceContent
+    : `${action.sourceContent}\n`;
+
+  return `${metadata}\n${body}`;
+}
+
+
 export function parseManagedRule(text: string): ParsedManagedRule {
   if (!text.startsWith(MANAGED_RULE_HEADER)) {
     return { status: "unmanaged", managed: false };
@@ -87,12 +174,98 @@ export function parseManagedRule(text: string): ParsedManagedRule {
   };
 }
 
+export function parseManagedCommand(text: string): ParsedManagedCommand {
+  if (text.startsWith(MANAGED_COMMAND_HEADER)) {
+    const headerEnd = text.indexOf(MANAGED_RULE_END, MANAGED_COMMAND_HEADER.length);
+    if (headerEnd === -1) {
+      return { status: "malformed", managed: true, error: "managed header is not closed" };
+    }
+
+    const headerText = text.slice(0, headerEnd).trimEnd();
+    const metadataResult = parseCommandMetadata(headerText);
+    if (typeof metadataResult === "string") {
+      return { status: "malformed", managed: true, error: metadataResult };
+    }
+
+    const afterHeader = text.slice(headerEnd + MANAGED_RULE_END.length).replace(/^\r?\n/, "");
+    const frontmatterResult = parseFrontmatter(afterHeader);
+    if (typeof frontmatterResult === "string") {
+      return { status: "malformed", managed: true, error: frontmatterResult };
+    }
+
+    return {
+      status: "managed",
+      managed: true,
+      metadata: metadataResult,
+      frontmatter: frontmatterResult.frontmatter,
+      body: stripTrailingNewline(frontmatterResult.body),
+    };
+  }
+
+  const frontmatterResult = parseFrontmatter(text);
+  if (typeof frontmatterResult === "string") {
+    if (
+      (text.startsWith("---\n") || text.startsWith("---\r\n")) &&
+      text.includes(`${MANAGED_COMMAND_FRONTMATTER_KEY}:`)
+    ) {
+      return { status: "malformed", managed: true, error: frontmatterResult };
+    }
+    return { status: "unmanaged", managed: false };
+  }
+
+  if (!frontmatterResult.frontmatter[MANAGED_COMMAND_FRONTMATTER_KEY]) {
+    return { status: "unmanaged", managed: false };
+  }
+
+  const metadataResult = parseCommandFrontmatterMetadata(frontmatterResult.frontmatter);
+  if (typeof metadataResult === "string") {
+    return { status: "malformed", managed: true, error: metadataResult };
+  }
+
+  return {
+    status: "managed",
+    managed: true,
+    metadata: metadataResult,
+    frontmatter: frontmatterResult.frontmatter,
+    body: stripTrailingNewline(frontmatterResult.body),
+  };
+}
+
+export function parseManagedExtension(text: string): ParsedManagedExtension {
+  if (!text.startsWith(MANAGED_EXTENSION_HEADER)) {
+    return { status: "unmanaged", managed: false };
+  }
+
+  const headerEnd = text.indexOf(MANAGED_EXTENSION_END, MANAGED_EXTENSION_HEADER.length);
+  if (headerEnd === -1) {
+    return { status: "malformed", managed: true, error: "managed extension header is not closed" };
+  }
+
+  const headerText = text.slice(0, headerEnd).trimEnd();
+  const metadataResult = parseExtensionMetadata(headerText);
+  if (typeof metadataResult === "string") {
+    return { status: "malformed", managed: true, error: metadataResult };
+  }
+
+  const body = text.slice(headerEnd + MANAGED_EXTENSION_END.length).replace(/^\r?\n/, "");
+  return {
+    status: "managed",
+    managed: true,
+    metadata: metadataResult,
+    body: stripTrailingNewline(body),
+  };
+}
+
 function renderFrontmatter(action: WriteRuleAction): string {
   if (action.mode === "ttsr") {
     if (!action.condition) {
       throw new Error(`TTSR rule ${action.slug} is missing a condition`);
     }
-    return `condition: ${frontmatterScalarLiteral(action.condition)}`;
+    return [
+      `condition: ${frontmatterScalarLiteral(action.condition)}`,
+      ...(action.triggers ? [`triggers: ${frontmatterScalarLiteral(action.triggers)}`] : []),
+      `scope: ${frontmatterScalarLiteral(action.scope ?? "text")}`,
+    ].join("\n");
   }
 
   const description = action.description ?? deriveRuleDescription(action.sourceContent) ?? `Use ${action.sourceName} when relevant.`;
@@ -165,6 +338,105 @@ function parseMetadata(headerText: string): ManagedRuleMetadata | string {
   };
 }
 
+function parseCommandMetadata(headerText: string): ManagedCommandMetadata | string {
+  const lines = headerText.split(/\r?\n/);
+  if (lines[0] !== MANAGED_COMMAND_HEADER) {
+    return "managed command header marker is invalid";
+  }
+
+  const raw: Record<string, string> = {};
+  for (const line of lines.slice(1)) {
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    raw[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+  }
+
+  return parseCommandMetadataFields(raw);
+}
+
+function parseCommandFrontmatterMetadata(frontmatter: Record<string, string>): ManagedCommandMetadata | string {
+  if (frontmatter[MANAGED_COMMAND_FRONTMATTER_KEY] !== MANAGED_COMMAND_FRONTMATTER_VERSION) {
+    return "managed command metadata has invalid version";
+  }
+
+  return parseCommandMetadataFields({
+    version: frontmatter[MANAGED_COMMAND_FRONTMATTER_KEY],
+    sourceId: frontmatter.sourceId,
+    sourceName: frontmatter.sourceName,
+    sourceHash: frontmatter.sourceHash,
+    slug: frontmatter.slug,
+    commandName: frontmatter.commandName,
+    sourceBytes: frontmatter.sourceBytes,
+  });
+}
+
+function parseCommandMetadataFields(raw: Record<string, string | undefined>): ManagedCommandMetadata | string {
+  const versionRaw = raw.version;
+  const sourceId = raw.sourceId;
+  const sourceName = raw.sourceName;
+  const sourceHash = raw.sourceHash;
+  const slug = raw.slug;
+  const commandName = raw.commandName;
+  const sourceBytesRaw = raw.sourceBytes;
+  if (!versionRaw) return "managed command metadata missing version";
+  if (!sourceId) return "managed command metadata missing sourceId";
+  if (!sourceName) return "managed command metadata missing sourceName";
+  if (!sourceHash) return "managed command metadata missing sourceHash";
+  if (!slug) return "managed command metadata missing slug";
+  if (!commandName) return "managed command metadata missing commandName";
+  if (!sourceBytesRaw) return "managed command metadata missing sourceBytes";
+
+  const version = Number(versionRaw);
+  const sourceBytes = Number(sourceBytesRaw);
+  if (!Number.isInteger(version) || version <= 0) return "managed command metadata has invalid version";
+  if (!Number.isInteger(sourceBytes) || sourceBytes < 0) return "managed command metadata has invalid sourceBytes";
+
+  return {
+    version,
+    sourceId,
+    sourceName,
+    sourceHash,
+    slug,
+    commandName,
+    sourceBytes,
+  };
+}
+
+function parseExtensionMetadata(headerText: string): ManagedExtensionMetadata | string {
+  const lines = headerText.split(/\r?\n/);
+  if (lines[0] !== MANAGED_EXTENSION_HEADER) {
+    return "managed extension header marker is invalid";
+  }
+
+  const raw: Record<string, string> = {};
+  for (const line of lines.slice(1)) {
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    raw[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+  }
+
+  const required = ["version", "sourceId", "sourceName", "sourceHash", "slug", "extensionName", "sourceBytes"];
+  for (const key of required) {
+    if (!raw[key]) return `managed extension metadata missing ${key}`;
+  }
+
+  const version = Number(raw.version);
+  const sourceBytes = Number(raw.sourceBytes);
+  if (!Number.isInteger(version) || version <= 0) return "managed extension metadata has invalid version";
+  if (!Number.isInteger(sourceBytes) || sourceBytes < 0) return "managed extension metadata has invalid sourceBytes";
+
+  return {
+    version,
+    sourceId: raw.sourceId,
+    sourceName: raw.sourceName,
+    sourceHash: raw.sourceHash,
+    slug: raw.slug,
+    extensionName: raw.extensionName,
+    sourceBytes,
+  };
+}
+
+
 function parseFrontmatter(text: string): { frontmatter: Record<string, string>; body: string } | string {
   if (!text.startsWith("---\n") && !text.startsWith("---\r\n")) {
     return "managed frontmatter is missing opening delimiter";

package/src/context/runbook-extension-template.ts

@@ -0,0 +1,193 @@
+export const RUNBOOK_EXTENSION_NAME = "supipowers-runbook";
+export const RUNBOOK_EXTENSION_PATH = ".omp/extensions/supipowers-runbook.ts";
+
+export const RUNBOOK_EXTENSION_SOURCE = `import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+
+type RuleBucket = "ttsr" | "always" | "rulebook" | "inactive";
+
+interface RuleInfo {
+  name: string;
+  description: string | null;
+  condition: string[];
+  triggers: string[];
+  scope: string[];
+  alwaysApply: boolean;
+  source: string;
+  bucket: RuleBucket;
+}
+
+function decodeScalar(raw: string): string {
+  const value = raw.trim();
+  if (value.length === 0) return "";
+  if (value.startsWith('"')) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value.slice(1, value.endsWith('"') ? -1 : undefined);
+    }
+  }
+  if (value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1);
+  return value;
+}
+
+function parseFrontmatter(text: string): { metadata: Record<string, string | string[]>; body: string } {
+  if (!text.startsWith("---\n")) return { metadata: {}, body: text.trim() };
+  const close = text.indexOf("\n---", 4);
+  if (close === -1) return { metadata: {}, body: text.trim() };
+  const raw = text.slice(4, close);
+  const bodyStart = text.indexOf("\n", close + 4);
+  const body = bodyStart === -1 ? "" : text.slice(bodyStart + 1).trim();
+  const metadata: Record<string, string | string[]> = {};
+  let currentKey: string | null = null;
+
+  for (const line of raw.split(/\r?\n/)) {
+    const keyMatch = /^(\\w+):\\s*(.*)$/.exec(line);
+    if (keyMatch) {
+      currentKey = keyMatch[1];
+      const value = keyMatch[2].trim();
+      metadata[currentKey] = value.length === 0 ? [] : decodeScalar(value);
+      continue;
+    }
+    const listMatch = /^\\s*-\\s*(.*)$/.exec(line);
+    if (listMatch && currentKey) {
+      const existing = metadata[currentKey];
+      const values = Array.isArray(existing) ? existing : existing ? [existing] : [];
+      values.push(decodeScalar(listMatch[1]));
+      metadata[currentKey] = values;
+    }
+  }
+
+  return { metadata, body };
+}
+
+function asList(value: string | string[] | undefined): string[] {
+  if (Array.isArray(value)) return value.filter(Boolean);
+  if (!value) return [];
+  return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+}
+
+function nameFromPath(filePath: string): string {
+  const base = basename(filePath);
+  const ext = extname(base);
+  return ext ? base.slice(0, -ext.length) : base;
+}
+
+function bucket(rule: Pick<RuleInfo, "condition" | "alwaysApply" | "description">): RuleBucket {
+  if (rule.condition.length > 0) return "ttsr";
+  if (rule.alwaysApply) return "always";
+  if (rule.description) return "rulebook";
+  return "inactive";
+}
+
+function discoverRules(cwd: string): RuleInfo[] {
+  const dir = join(cwd, ".omp", "rules");
+  if (!existsSync(dir)) return [];
+  const rules: RuleInfo[] = [];
+  for (const entry of readdirSync(dir).sort()) {
+    const filePath = join(dir, entry);
+    if (![".md", ".mdc"].includes(extname(filePath))) continue;
+    try {
+      if (!statSync(filePath).isFile()) continue;
+      const parsed = parseFrontmatter(readFileSync(filePath, "utf8"));
+      const info: RuleInfo = {
+        name: nameFromPath(filePath),
+        description: typeof parsed.metadata.description === "string" ? parsed.metadata.description : null,
+        condition: asList(parsed.metadata.condition),
+        triggers: asList(parsed.metadata.triggers ?? parsed.metadata.triggerDescription),
+        scope: asList(parsed.metadata.scope),
+        alwaysApply: parsed.metadata.alwaysApply === "true",
+        source: filePath,
+        bucket: "inactive",
+      };
+      info.bucket = bucket(info);
+      rules.push(info);
+    } catch {
+      // Keep runbook display best-effort; unreadable rules should not break the command.
+    }
+  }
+  return rules;
+}
+
+function describeScope(rule: RuleInfo): string {
+  if (rule.scope.length === 0) return "assistant prose and tool-call text";
+  const labels = rule.scope.map((scope) => {
+    const normalized = scope.toLowerCase();
+    if (normalized === "text") return "assistant prose";
+    if (normalized === "thinking") return "assistant thinking";
+    if (normalized === "tool" || normalized === "toolcall") return "all tool-call text";
+    return "tool scope " + scope;
+  });
+  return labels.join(", ") + " only";
+}
+
+function formatRule(rule: RuleInfo): string[] {
+  const lines = ["  " + rule.name];
+  if (rule.description) lines.push("    Description: " + rule.description);
+  if (rule.bucket === "ttsr") {
+    lines.push("    Applies: when assistant output matches the trigger phrase(s)");
+    if (rule.triggers.length > 0) {
+      lines.push("    Triggers: " + rule.triggers.join(", "));
+    } else {
+      lines.push("    Triggers: exact regex only; add triggers: frontmatter for readability");
+      for (const condition of rule.condition) lines.push("      - " + condition);
+    }
+    lines.push("    Scope: " + describeScope(rule));
+  } else if (rule.bucket === "always") {
+    lines.push("    Applies: always injected at session start");
+  } else if (rule.bucket === "rulebook") {
+    lines.push("    Applies: on demand via rule://" + rule.name);
+  } else {
+    lines.push("    Applies: inactive in prompt surfaces");
+  }
+  return lines;
+}
+
+function formatRules(cwd: string, onlyTtsr: boolean): string {
+  const rules = discoverRules(cwd).filter((rule) => !onlyTtsr || rule.bucket === "ttsr");
+  const lines = [onlyTtsr ? "/runbook rules ttsr" : "/runbook rules", "", "Rules: " + rules.length, ""];
+  if (rules.length === 0) return [...lines, "  none"].join("\\n");
+  for (const rule of rules.sort((a, b) => a.name.localeCompare(b.name))) {
+    lines.push(...formatRule(rule), "");
+  }
+  return lines.join("\\n").trimEnd();
+}
+
+function formatCommands(api: any): string {
+  const commands = typeof api.getCommands === "function" ? api.getCommands() : [];
+  const lines = ["/runbook commands", "", "Registered slash commands: " + commands.length, ""];
+  for (const command of [...commands].sort((a: any, b: any) => String(a.name).localeCompare(String(b.name)))) {
+    lines.push("  /" + command.name, "    " + (command.description ?? "No description"));
+  }
+  return lines.join("\\n");
+}
+
+function buildReport(api: any, cwd: string, args?: string): string {
+  const tokens = (args ?? "").trim().split(/\\s+/).filter(Boolean).map((token) => token.toLowerCase());
+  if (tokens[0] === "commands" || tokens[1] === "commands") return formatCommands(api);
+  if (tokens[0] === "ttsr" || tokens[1] === "ttsr") return formatRules(cwd, true);
+  return formatRules(cwd, false);
+}
+
+export default function supipowersRunbook(api: any): void {
+  const handle = (args: string | undefined, ctx: any): void => {
+    if (!ctx?.hasUI || !ctx.ui?.notify) return;
+    ctx.ui.notify(buildReport(api, ctx.cwd ?? process.cwd(), args), "info");
+  };
+
+  api.registerCommand?.("runbook", {
+    description: "Show project rules, TTSR triggers, and slash commands without an LLM turn",
+    async handler(args: string | undefined, ctx: any): Promise<void> {
+      handle(args, ctx);
+    },
+  });
+
+  api.on?.("input", (event: any, ctx: any) => {
+    const text = String(event?.text ?? "").trim();
+    if (!text.startsWith("/runbook")) return;
+    const args = text.length > "/runbook".length ? text.slice("/runbook".length).trim() : undefined;
+    handle(args, ctx);
+    return { handled: true };
+  });
+}
+`;