supipowers 1.5.3 → 2.0.1

package/src/context/startup-optimizer.ts

@@ -0,0 +1,355 @@
+import { createHash } from "node:crypto";
+import type { ParsedSkill, PromptSection } from "./analyzer.js";
+import type { TechStack } from "./optimizer.js";
+
+export const STARTUP_OPTIMIZER_MANIFEST_VERSION = 1;
+export const TARGET_STARTUP_PROMPT_BYTES = 8_000 * 4;
+export const AGENTS_SPLIT_THRESHOLD_BYTES = TARGET_STARTUP_PROMPT_BYTES;
+
+export type OptimizationSourceType = "skill" | "section";
+export type RuleMode = "ttsr" | "rulebook";
+
+export interface OptimizationSource {
+  sourceId: string;
+  sourceName: string;
+  sourceType: OptimizationSourceType;
+  sourceHash: string;
+  slug: string;
+  bytes: number;
+  tokens: number;
+  content: string;
+}
+
+export interface WriteRuleAction {
+  kind: "write-rule";
+  mode: RuleMode;
+  sourceId: string;
+  sourceName: string;
+  sourceHash: string;
+  slug: string;
+  targetPath: string;
+  sourceBytes: number;
+  estimatedSavedBytes: number;
+  sourceContent: string;
+  condition?: string;
+  description?: string;
+}
+
+export type ManualDisableReason = "source-still-loaded" | "tech-stack-irrelevant";
+
+export interface ManualDisableAction {
+  kind: "manual-disable";
+  reason: ManualDisableReason;
+  sourceId: string;
+  sourceName: string;
+  sourceHash: string;
+  slug: string;
+  remediation: string;
+}
+
+export interface ManualAgentsSplitAction {
+  kind: "manual-agents-split";
+  sourceId: string;
+  sourceName: string;
+  sourceHash: string;
+  sourceBytes: number;
+  thresholdBytes: number;
+  remediation: string;
+}
+
+export type ManualOptimizationAction = ManualDisableAction | ManualAgentsSplitAction;
+export type OptimizationAction = WriteRuleAction | ManualOptimizationAction;
+
+export interface OptimizationWarning {
+  code: string;
+  message: string;
+  sourceId?: string;
+}
+
+export interface OptimizationPlan {
+  version: typeof STARTUP_OPTIMIZER_MANIFEST_VERSION;
+  targetBytes: number;
+  sourceSetHash: string;
+  beforeBytes: number;
+  estimatedAfterBytes: number;
+  estimatedSavedBytes: number;
+  sources: OptimizationSource[];
+  actions: OptimizationAction[];
+  warnings: OptimizationWarning[];
+}
+
+export interface BuildOptimizationPlanInput {
+  /**
+   * Original system prompt text. Used as the authoritative `beforeBytes` so the
+   * optimizer estimate matches the actual prompt size, even when `sections` and
+   * `skills` overlap (e.g. when `# Skills` content is also captured inside a
+   * containing section).
+   */
+  prompt: string;
+  sections: PromptSection[];
+  skills: ParsedSkill[];
+  techStack: TechStack;
+}
+
+interface BehaviorSkillSpec {
+  mode: "ttsr";
+  condition: string;
+}
+
+const BEHAVIOR_SKILLS: Record<string, BehaviorSkillSpec> = {
+  debugging: {
+    mode: "ttsr",
+    condition: String.raw`\b(?:debug(?:ging)?|root\s+cause|investigate|repro(?:duce|duction)?|failing\s+test)\b`,
+  },
+  tdd: {
+    mode: "ttsr",
+    condition: String.raw`\b(?:tdd|test\s+first|failing\s+test\s+first|red[-\s]+green[-\s]+refactor)\b`,
+  },
+  verification: {
+    mode: "ttsr",
+    condition: String.raw`\b(?:verify|verification|evidence|prove|proof|run\s+(?:the\s+)?(?:focused\s+)?tests?)\b`,
+  },
+  "receiving-code-review": {
+    mode: "ttsr",
+    condition: String.raw`\b(?:pr\s+feedback|code\s+review\s+comments?|reviewer\s+feedback|review\s+comments?)\b`,
+  },
+};
+
+const TECH_STACK_SKILLS: Record<string, { anyOf: Array<keyof TechStack>; values: string[] }> = {
+  "shadcn-ui": {
+    anyOf: ["frameworks", "tools"],
+    values: ["react", "next", "shadcn", "tailwind"],
+  },
+  "better-auth": {
+    anyOf: ["languages", "frameworks", "tools", "runtime"],
+    values: ["typescript", "javascript", "react", "next", "node", "bun"],
+  },
+  playwright: {
+    anyOf: ["tools"],
+    values: ["playwright"],
+  },
+};
+
+const ACTION_KIND_ORDER: Record<OptimizationAction["kind"], number> = {
+  "write-rule": 0,
+  "manual-disable": 1,
+  "manual-agents-split": 2,
+};
+
+export function hashOptimizationSource(content: string): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+export function slugifyOptimizationSource(value: string): string {
+  const slug = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || "source";
+}
+
+export function sourceSetHash(sources: Pick<OptimizationSource, "sourceId" | "sourceHash">[]): string {
+  const body = [...sources]
+    .sort((a, b) => a.sourceId.localeCompare(b.sourceId))
+    .map((source) => `${source.sourceId}:${source.sourceHash}`)
+    .join("\n");
+  return hashOptimizationSource(body);
+}
+
+export function buildOptimizationPlan(input: BuildOptimizationPlanInput): OptimizationPlan {
+  const sources = buildSources(input.sections, input.skills);
+  const actions: OptimizationAction[] = [];
+  const warnings: OptimizationWarning[] = [];
+
+  for (const source of sources) {
+    if (source.sourceType === "skill") {
+      const canonicalName = source.sourceName.toLowerCase();
+      const behavior = BEHAVIOR_SKILLS[canonicalName];
+      if (behavior) {
+        actions.push(buildWriteRuleAction(source, behavior.mode, behavior.condition));
+        actions.push(buildManualDisableAction(source, "source-still-loaded"));
+        continue;
+      }
+
+      if (isTechStackIrrelevant(canonicalName, input.techStack)) {
+        actions.push(buildManualDisableAction(source, "tech-stack-irrelevant"));
+        continue;
+      }
+
+      actions.push(buildWriteRuleAction(source, "rulebook"));
+      actions.push(buildManualDisableAction(source, "source-still-loaded"));
+      continue;
+    }
+
+    if (source.sourceName === "AGENTS.md" && source.bytes > AGENTS_SPLIT_THRESHOLD_BYTES) {
+      actions.push({
+        kind: "manual-agents-split",
+        sourceId: source.sourceId,
+        sourceName: source.sourceName,
+        sourceHash: source.sourceHash,
+        sourceBytes: source.bytes,
+        thresholdBytes: AGENTS_SPLIT_THRESHOLD_BYTES,
+        remediation:
+          "Split oversized AGENTS.md guidance into smaller scoped files or managed rules so startup context stays under the L6 target.",
+      });
+    }
+  }
+
+  // beforeBytes comes from the original prompt, not from summing source bytes:
+  // sections and skills overlap in practice (e.g. `# Skills` content appears
+  // inside a containing section), so summing would double-count.
+  const beforeBytes = byteLength(input.prompt);
+
+  // Sources whose content the user is expected to actually remove from the
+  // startup prompt: write-rule companions and tech-stack manual-disable
+  // actions. Deduplicated by sourceId because a write-rule action is paired
+  // with a `source-still-loaded` manual-disable for the same source.
+  const removedSourceIds = new Set<string>();
+  for (const action of actions) {
+    if (action.kind === "write-rule" || action.kind === "manual-disable") {
+      removedSourceIds.add(action.sourceId);
+    }
+  }
+  const estimatedSavedBytes = sources
+    .filter((source) => removedSourceIds.has(source.sourceId))
+    .reduce((sum, source) => sum + source.bytes, 0);
+  const estimatedAfterBytes = Math.max(0, beforeBytes - estimatedSavedBytes);
+
+  return {
+    version: STARTUP_OPTIMIZER_MANIFEST_VERSION,
+    targetBytes: TARGET_STARTUP_PROMPT_BYTES,
+    sourceSetHash: sourceSetHash(sources),
+    beforeBytes,
+    estimatedAfterBytes,
+    estimatedSavedBytes,
+    sources,
+    actions: sortActions(actions),
+    warnings,
+  };
+}
+
+function byteLength(value: string): number {
+  return new TextEncoder().encode(value).length;
+}
+
+function buildSources(sections: PromptSection[], skills: ParsedSkill[]): OptimizationSource[] {
+  const sourceMap = new Map<string, OptimizationSource>();
+
+  for (const skill of skills) {
+    const sourceName = skill.name.trim();
+    const canonicalName = sourceName.toLowerCase();
+    const sourceId = `skill:${canonicalName}`;
+    const content = canonicalSourceContent(skill.content);
+    sourceMap.set(sourceId, {
+      sourceId,
+      sourceName: canonicalName,
+      sourceType: "skill",
+      sourceHash: hashOptimizationSource(content),
+      slug: slugifyOptimizationSource(sourceId),
+      bytes: byteLength(content),
+      tokens: Math.ceil(content.length / 4),
+      content,
+    });
+  }
+
+  for (const section of sections) {
+    const sourceName = section.label.trim();
+    const sourceId = `section:${sourceName}`;
+    const content = canonicalSourceContent(section.content);
+    sourceMap.set(sourceId, {
+      sourceId,
+      sourceName,
+      sourceType: "section",
+      sourceHash: hashOptimizationSource(content),
+      slug: slugifyOptimizationSource(sourceId),
+      bytes: byteLength(content),
+      tokens: Math.ceil(content.length / 4),
+      content,
+    });
+  }
+
+  return [...sourceMap.values()].sort((a, b) => a.sourceId.localeCompare(b.sourceId));
+}
+
+/**
+ * Canonicalize a source body for hashing/sizing: strip a single trailing newline.
+ *
+ * The renderer adds a trailing newline at file write time for POSIX-friendly EOF,
+ * and the parser strips it back. Hashing canonical (no-trailing-newline) form keeps
+ * the round trip stable regardless of whether the caller passed content with or
+ * without an EOF newline.
+ */
+function canonicalSourceContent(content: string): string {
+  if (content.endsWith("\r\n")) return content.slice(0, -2);
+  if (content.endsWith("\n")) return content.slice(0, -1);
+  return content;
+}
+
+function buildWriteRuleAction(
+  source: OptimizationSource,
+  mode: RuleMode,
+  condition?: string,
+): WriteRuleAction {
+  return {
+    kind: "write-rule",
+    mode,
+    sourceId: source.sourceId,
+    sourceName: source.sourceName,
+    sourceHash: source.sourceHash,
+    slug: source.slug,
+    targetPath: `.omp/rules/${source.slug}.md`,
+    sourceBytes: source.bytes,
+    estimatedSavedBytes: source.bytes,
+    sourceContent: source.content,
+    ...(condition ? { condition } : {}),
+  };
+}
+
+function buildManualDisableAction(
+  source: OptimizationSource,
+  reason: ManualDisableReason,
+): ManualDisableAction {
+  const remediation = reason === "tech-stack-irrelevant"
+    ? `Disable ${source.sourceName}; it is not relevant to the detected project tech stack.`
+    : `Disable the original ${source.sourceName} skill once the managed rule is available so startup context is actually reduced.`;
+
+  return {
+    kind: "manual-disable",
+    reason,
+    sourceId: source.sourceId,
+    sourceName: source.sourceName,
+    sourceHash: source.sourceHash,
+    slug: source.slug,
+    remediation,
+  };
+}
+
+function isTechStackIrrelevant(skillName: string, techStack: TechStack): boolean {
+  const rule = TECH_STACK_SKILLS[skillName];
+  if (!rule) return false;
+
+  for (const key of rule.anyOf) {
+    const value = techStack[key];
+    if (Array.isArray(value)) {
+      if (value.some((entry) => rule.values.includes(entry.toLowerCase()))) return false;
+    } else if (typeof value === "string" && rule.values.includes(value.toLowerCase())) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function sortActions(actions: OptimizationAction[]): OptimizationAction[] {
+  return [...actions].sort((a, b) => {
+    const kindDelta = ACTION_KIND_ORDER[a.kind] - ACTION_KIND_ORDER[b.kind];
+    if (kindDelta !== 0) return kindDelta;
+    const sourceDelta = a.sourceId.localeCompare(b.sourceId);
+    if (sourceDelta !== 0) return sourceDelta;
+    if (a.kind === "write-rule" && b.kind === "write-rule") {
+      return a.mode.localeCompare(b.mode);
+    }
+    return 0;
+  });
+}

package/src/context/tokenignore.ts

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto";
+
+export const TOKENIGNORE_BEGIN_MARKER = "# BEGIN supipowers context optimizer managed block";
+export const TOKENIGNORE_END_MARKER = "# END supipowers context optimizer managed block";
+
+export const DEFAULT_TOKENIGNORE_ENTRIES = [
+  ".omp/supipowers/reviews/",
+  ".omp/supipowers/debug/",
+  ".omp/supipowers/reports/",
+  ".omp/supipowers/fix-pr-sessions/",
+  ".omp/supipowers/qa-sessions/",
+  ".omp/supipowers/ui-design/",
+  ".omp/supipowers/visual/",
+  ".omp/supipowers/sessions/*.db",
+  ".omp/supipowers/sessions/*.db-*",
+  "dist/",
+  "coverage/",
+];
+
+export interface ManagedTokenignoreMergeResult {
+  content: string;
+  entries: string[];
+  hash: string;
+}
+
+export type ParsedManagedTokenignore =
+  | { status: "unmanaged"; managed: false }
+  | {
+      status: "managed";
+      managed: true;
+      entries: string[];
+      hash: string;
+      expectedHash: string;
+      hashMatches: boolean;
+    }
+  | { status: "malformed"; managed: true; error: string };
+
+export function hashTokenignoreEntries(entries: string[]): string {
+  return createHash("sha256")
+    .update(normalizeEntries(entries).sort().join("\n"))
+    .digest("hex");
+}
+
+export function renderManagedTokenignoreBlock(entries: string[]): string {
+  const normalized = normalizeEntries(entries);
+  const hash = hashTokenignoreEntries(normalized);
+  return [
+    TOKENIGNORE_BEGIN_MARKER,
+    "# Managed by supipowers. Edit entries outside this block.",
+    `# hash: ${hash}`,
+    ...normalized,
+    TOKENIGNORE_END_MARKER,
+  ].join("\n");
+}
+
+export function mergeManagedTokenignore(
+  existing: string | null | undefined,
+  entries: string[],
+): ManagedTokenignoreMergeResult {
+  const normalized = normalizeEntries(entries);
+  const hash = hashTokenignoreEntries(normalized);
+  const block = renderManagedTokenignoreBlock(normalized);
+  const userContent = removeManagedTokenignoreBlocks(existing ?? "").trimEnd();
+  const content = userContent.length > 0
+    ? `${userContent}\n\n${block}\n`
+    : `${block}\n`;
+
+  return { content, entries: normalized, hash };
+}
+
+export function parseManagedTokenignore(text: string | null | undefined): ParsedManagedTokenignore {
+  const content = text ?? "";
+  const begin = content.indexOf(TOKENIGNORE_BEGIN_MARKER);
+  if (begin === -1) return { status: "unmanaged", managed: false };
+
+  const end = content.indexOf(TOKENIGNORE_END_MARKER, begin + TOKENIGNORE_BEGIN_MARKER.length);
+  if (end === -1) {
+    return { status: "malformed", managed: true, error: "managed tokenignore block is missing end marker" };
+  }
+
+  const block = content.slice(begin, end + TOKENIGNORE_END_MARKER.length);
+  const lines = block.split(/\r?\n/);
+  let hash: string | null = null;
+  const entries: string[] = [];
+
+  for (const rawLine of lines.slice(1, -1)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    if (line.startsWith("# hash:")) {
+      hash = line.slice("# hash:".length).trim();
+      continue;
+    }
+    if (line.startsWith("#")) continue;
+    entries.push(line);
+  }
+
+  if (!hash) {
+    return { status: "malformed", managed: true, error: "managed tokenignore block is missing hash" };
+  }
+
+  const normalized = normalizeEntries(entries);
+  const expectedHash = hashTokenignoreEntries(normalized);
+  return {
+    status: "managed",
+    managed: true,
+    entries: normalized,
+    hash,
+    expectedHash,
+    hashMatches: hash === expectedHash,
+  };
+}
+
+function normalizeEntries(entries: string[]): string[] {
+  const seen = new Set<string>();
+  const normalized: string[] = [];
+
+  for (const entry of entries) {
+    const trimmed = entry.trim();
+    if (!trimmed) continue;
+    if (seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    normalized.push(trimmed);
+  }
+
+  return normalized;
+}
+
+function removeManagedTokenignoreBlocks(existing: string): string {
+  let output = existing;
+
+  while (true) {
+    const begin = output.indexOf(TOKENIGNORE_BEGIN_MARKER);
+    if (begin === -1) return output;
+    const end = output.indexOf(TOKENIGNORE_END_MARKER, begin + TOKENIGNORE_BEGIN_MARKER.length);
+    const removeEnd = end === -1
+      ? output.length
+      : end + TOKENIGNORE_END_MARKER.length + trailingNewlineLength(output, end + TOKENIGNORE_END_MARKER.length);
+    output = output.slice(0, begin) + output.slice(removeEnd);
+  }
+}
+
+function trailingNewlineLength(value: string, index: number): number {
+  if (value.slice(index, index + 2) === "\r\n") return 2;
+  if (value[index] === "\n") return 1;
+  return 0;
+}

package/src/context-mode/cache-handle.ts

@@ -0,0 +1,49 @@
+// src/context-mode/cache-handle.ts
+
+const HANDLE_PREFIX = "cache://";
+const SHA256_HEX_RE = /^[a-f0-9]{64}$/;
+const RENDER_SHA256_RE = /^[a-fA-F0-9]{64}$/;
+const MAX_DESCRIBED_VALUE_CHARS = 120;
+const INVALID_HANDLE_REQUIREMENT =
+  "must be cache:// followed by 64 lowercase hexadecimal characters";
+
+export type CacheHandleParseResult =
+  | { ok: true; handle: string; sha256: string }
+  | { ok: false; message: string };
+
+export function renderCacheHandle(sha256: string): string {
+  const normalized = sha256.trim().toLowerCase();
+  if (!RENDER_SHA256_RE.test(normalized)) {
+    throw new Error(`invalid cache sha256: ${INVALID_HANDLE_REQUIREMENT}`);
+  }
+  return `${HANDLE_PREFIX}${normalized}`;
+}
+
+export function parseCacheHandle(value: string): CacheHandleParseResult {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith(HANDLE_PREFIX)) {
+    return invalidCacheHandle(trimmed);
+  }
+
+  const sha256 = trimmed.slice(HANDLE_PREFIX.length);
+  if (!SHA256_HEX_RE.test(sha256)) {
+    return invalidCacheHandle(trimmed);
+  }
+
+  return { ok: true, handle: renderCacheHandle(sha256), sha256 };
+}
+
+export function describeInvalidCacheHandle(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.length > MAX_DESCRIBED_VALUE_CHARS) {
+    return `value with length ${trimmed.length}`;
+  }
+  return trimmed;
+}
+
+function invalidCacheHandle(value: string): CacheHandleParseResult {
+  return {
+    ok: false,
+    message: `invalid cache handle (${describeInvalidCacheHandle(value)}): ${INVALID_HANDLE_REQUIREMENT}`,
+  };
+}

package/src/context-mode/cache-preview.ts

@@ -0,0 +1,71 @@
+// src/context-mode/cache-preview.ts
+
+export const DEFAULT_CACHE_PREVIEW_CHARS = 4 * 1024;
+export const DEFAULT_CACHE_OPEN_CHARS = 64 * 1024;
+export const HARD_CACHE_OPEN_CHARS = 100 * 1024;
+
+const PREVIEW_OMISSION_MARKER = "\n… omitted …\n";
+
+export function buildCachePreview(
+  text: string,
+  maxChars = DEFAULT_CACHE_PREVIEW_CHARS,
+): string {
+  const chars = Array.from(text);
+  const max = normalizeNonNegativeInteger(maxChars, DEFAULT_CACHE_PREVIEW_CHARS);
+  if (max === 0) return "";
+  if (chars.length <= max) return text;
+
+  const markerChars = Array.from(PREVIEW_OMISSION_MARKER);
+  if (max <= markerChars.length) {
+    return markerChars.slice(0, max).join("");
+  }
+
+  const contentBudget = max - markerChars.length;
+  const headCount = Math.ceil(contentBudget / 2);
+  const tailCount = Math.floor(contentBudget / 2);
+
+  return [
+    ...chars.slice(0, headCount),
+    ...markerChars,
+    ...chars.slice(chars.length - tailCount),
+  ].join("");
+}
+
+export function sliceCachedText(
+  text: string,
+  offset = 0,
+  limit = DEFAULT_CACHE_OPEN_CHARS,
+): {
+  text: string;
+  offset: number;
+  returnedChars: number;
+  totalChars: number;
+  nextOffset: number | null;
+} {
+  const chars = Array.from(text);
+  const totalChars = chars.length;
+  const normalizedOffset = Math.min(
+    normalizeNonNegativeInteger(offset, 0),
+    totalChars,
+  );
+  const normalizedLimit = Math.min(
+    normalizeNonNegativeInteger(limit, DEFAULT_CACHE_OPEN_CHARS),
+    HARD_CACHE_OPEN_CHARS,
+  );
+
+  const end = Math.min(normalizedOffset + normalizedLimit, totalChars);
+  const sliced = chars.slice(normalizedOffset, end).join("");
+
+  return {
+    text: sliced,
+    offset: normalizedOffset,
+    returnedChars: end - normalizedOffset,
+    totalChars,
+    nextOffset: end < totalChars ? end : null,
+  };
+}
+
+function normalizeNonNegativeInteger(value: number, fallback: number): number {
+  if (!Number.isFinite(value)) return fallback;
+  return Math.max(0, Math.floor(value));
+}