@hasna/instructions 0.6.0 → 0.7.0

package/dist/chunks/index-z3ma4aqk.js

@@ -0,0 +1,532 @@
+// @bun
+import {
+  ANTIGRAVITY_RULE_FILE_CHAR_LIMIT,
+  SESSION_RENDERER_OWNER_ID,
+  SESSION_RENDER_EXCLUSIVE_MANAGED_PATHS,
+  SESSION_RENDER_MANIFEST_RELATIVE_PATH,
+  SESSION_RENDER_OWNED_CONFIG_TARGETS,
+  SESSION_RENDER_SCHEMA,
+  applyTransform,
+  detectMachineContext,
+  isCursorGlobalAuthorityPath,
+  isRetiredOrUnsupportedConfigAgent,
+  isSecretVarName,
+  machineContextToVariables,
+  redactFormatForTarget,
+  renderMachineAwareContentPreview,
+  resolveConfigStore,
+  resolveProfileVariables,
+  scanSecrets,
+  stampCursorGlobalAuthorityMarker
+} from "./index-7m4j8a33.js";
+import {
+  ConfigApplyError,
+  parseTemplateVars
+} from "./index-n3fjspr0.js";
+
+// src/lib/apply.ts
+import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, realpathSync, writeFileSync } from "fs";
+import { basename, dirname as dirname2, isAbsolute, join as join2, relative as relative2, resolve, sep as sep2 } from "path";
+import { homedir } from "os";
+
+// src/lib/session-render-ownership.ts
+import { existsSync, readFileSync, statSync } from "fs";
+import { dirname, join, parse, relative, sep } from "path";
+var MANIFEST_ANCESTOR_LIMIT = 24;
+var MANAGED_PATH_SEGMENTS = SESSION_RENDER_EXCLUSIVE_MANAGED_PATHS.map((managedPath) => managedPath.split("/").filter(Boolean));
+var manifestCache = new Map;
+function toSegments(absolutePath) {
+  return absolutePath.replaceAll("\\", "/").split("/").filter(Boolean);
+}
+function pathIsSessionRenderManagedDir(absolutePath) {
+  const segments = toSegments(absolutePath);
+  return MANAGED_PATH_SEGMENTS.some((managed) => {
+    if (managed.length === 0 || managed.length > segments.length)
+      return false;
+    for (let start = 0;start + managed.length <= segments.length; start += 1) {
+      if (managed.every((segment, offset) => segments[start + offset] === segment))
+        return true;
+    }
+    return false;
+  });
+}
+function readManifestRelativePaths(manifestPath) {
+  let stats;
+  try {
+    if (!existsSync(manifestPath))
+      return null;
+    stats = statSync(manifestPath);
+  } catch {
+    return null;
+  }
+  const cached = manifestCache.get(manifestPath);
+  if (cached && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) {
+    return cached.relativePaths;
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+  } catch {
+    return null;
+  }
+  if (manifest?.schema !== SESSION_RENDER_SCHEMA || !Array.isArray(manifest.files))
+    return null;
+  const writerId = manifest.targetOwner?.writer?.id;
+  if (writerId !== undefined && writerId !== SESSION_RENDERER_OWNER_ID)
+    return null;
+  const relativePaths = new Set(manifest.files.map((file) => file?.relativePath).filter((relativePath) => typeof relativePath === "string").map((relativePath) => relativePath.replaceAll("\\", "/")));
+  manifestCache.set(manifestPath, { mtimeMs: stats.mtimeMs, size: stats.size, relativePaths });
+  return relativePaths;
+}
+function sessionRenderManifestClaimsPath(absolutePath) {
+  const root = parse(absolutePath).root;
+  let home = dirname(absolutePath);
+  for (let depth = 0;depth < MANIFEST_ANCESTOR_LIMIT; depth += 1) {
+    const manifestPath = join(home, ...SESSION_RENDER_MANIFEST_RELATIVE_PATH.split("/"));
+    const relativePaths = readManifestRelativePaths(manifestPath);
+    if (relativePaths) {
+      const claimed = relative(home, absolutePath).split(sep).join("/");
+      if (relativePaths.has(claimed))
+        return true;
+    }
+    const parent = dirname(home);
+    if (parent === home || home === root)
+      break;
+    home = parent;
+  }
+  return false;
+}
+function sessionRenderOwnsPath(absolutePath) {
+  return pathIsSessionRenderManagedDir(absolutePath) || sessionRenderManifestClaimsPath(absolutePath);
+}
+
+// src/lib/apply.ts
+function getConfigHome() {
+  return process.env["CONFIGS_HOME"] || process.env["HOME"] || homedir();
+}
+function expandPath(p) {
+  if (p.startsWith("~/")) {
+    return resolve(getConfigHome(), p.slice(2));
+  }
+  return resolve(p);
+}
+function compactPathForConfigHome(p) {
+  const absolute = resolve(p);
+  const configHome = resolve(getConfigHome());
+  const conventionalHome = resolve(process.env["HOME"] || homedir());
+  if (configHome !== conventionalHome)
+    return absolute;
+  const rel = relative2(configHome, absolute);
+  if (!rel || rel === ".." || rel.startsWith(`..${sep2}`) || isAbsolute(rel))
+    return absolute;
+  return `~/${rel}`;
+}
+function normalizeTargetPath(p) {
+  const expanded = expandPath(p);
+  try {
+    return realpathSync(expanded);
+  } catch {
+    let current = expanded;
+    const missingSegments = [];
+    while (true) {
+      if (existsSync2(current)) {
+        try {
+          return resolve(realpathSync(current), ...missingSegments);
+        } catch {
+          return expanded;
+        }
+      }
+      const parent = dirname2(current);
+      const name = basename(current);
+      if (parent === current)
+        return expanded;
+      missingSegments.unshift(name);
+      current = parent;
+    }
+  }
+}
+async function writeConfigResult(config, targetPath, content, opts, meta = {}) {
+  const variables = opts.vars ?? {};
+  const renderedTarget = renderForApply(targetPath, variables);
+  const rendered = renderForApply(content, variables);
+  const renderedTargetPath = renderedTarget.content;
+  const renderedContent = rendered.content;
+  const targetAgent = meta.agent ?? config.agent;
+  if (sessionRendererOwnsTarget(renderedTargetPath, opts)) {
+    throw new ConfigApplyError(`Config "${config.name}" targets ${normalizeTargetPath(renderedTargetPath)}, which is owned by ${SESSION_RENDERER_OWNER_ID}; use the Instructions session renderer.`);
+  }
+  if (isAntigravityRuleTarget(targetAgent, renderedTargetPath) && renderedContent.length > ANTIGRAVITY_RULE_FILE_CHAR_LIMIT) {
+    throw new ConfigApplyError(`Antigravity rule file ${renderedTargetPath} is ${renderedContent.length} characters; split it before applying because Antigravity limits rule files to ${ANTIGRAVITY_RULE_FILE_CHAR_LIMIT} characters.`);
+  }
+  const path = expandPath(renderedTargetPath);
+  const renderedForTarget = isCursorGlobalAuthorityPath(path) ? stampCursorGlobalAuthorityMarker(renderedContent) : renderedContent;
+  const previousContent = existsSync2(path) ? readFileSync2(path, "utf-8") : null;
+  const changed = previousContent !== renderedForTarget;
+  if (!opts.dryRun) {
+    const dir = dirname2(path);
+    if (!existsSync2(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    if (previousContent !== null && changed) {
+      const store = opts.store ?? resolveConfigStore();
+      await store.createSnapshot(config.id, previousContent, config.version);
+    }
+    writeFileSync(path, renderedForTarget, "utf-8");
+  }
+  return {
+    config_id: config.id,
+    path,
+    previous_content: previousContent,
+    new_content: renderedForTarget,
+    dry_run: opts.dryRun ?? false,
+    changed,
+    primary_changed: changed,
+    unresolved_template_vars: [...new Set([
+      ...renderedTarget.unresolved,
+      ...rendered.unresolved
+    ])].sort(),
+    ...meta
+  };
+}
+function renderForApply(content, variables) {
+  return renderMachineAwareContentPreview(content, variables);
+}
+function wouldDestroyACredential(targetPath, renderedContent, format) {
+  const secretTokens = parseTemplateVars(renderedContent).filter(isSecretVarName);
+  if (secretTokens.length === 0)
+    return [];
+  let current;
+  try {
+    const path = expandPath(targetPath);
+    if (!existsSync2(path))
+      return [];
+    current = readFileSync2(path, "utf-8");
+  } catch {
+    return secretTokens;
+  }
+  if (current === renderedContent)
+    return [];
+  if (scanSecrets(current, redactFormatForTarget(targetPath, format)).length > 0)
+    return secretTokens;
+  return secretTokens.filter((name) => countPlaceholder(current, name) < countPlaceholder(renderedContent, name));
+}
+function countPlaceholder(content, name) {
+  return content.match(new RegExp(`\\{\\{${name}(?::[^}]*)?\\}\\}`, "g"))?.length ?? 0;
+}
+async function resolveApplyVariables(opts) {
+  const machine = detectMachineContext();
+  let base;
+  try {
+    const store = opts.store ?? resolveConfigStore();
+    const profile = await store.resolveProfileForMachine(machine);
+    base = resolveProfileVariables(profile, machine);
+  } catch {
+    base = machineContextToVariables(machine);
+  }
+  return { ...base, ...opts.vars ?? {} };
+}
+function isAntigravityRuleTarget(agent, targetPath) {
+  return agent === "antigravity" && /\.(md|mdc|markdown)$/i.test(targetPath);
+}
+function isGeneratedOutputTarget(config, configs, opts) {
+  const primary = canonicalConfigApplyBehavior(config, opts, configs).primary;
+  if (!primary)
+    return false;
+  return configs.some((candidate) => candidate.id !== config.id && canonicalConfigApplyBehavior(candidate, opts, configs).outputs.some((output) => output.path === primary.path));
+}
+async function applyConfig(config, opts = {}) {
+  if (config.kind === "reference") {
+    throw new ConfigApplyError(`Config "${config.name}" is a reference (kind=reference) and has no target_path \u2014 cannot apply to disk.`);
+  }
+  if (opts.outputAgent && isRetiredOrUnsupportedConfigAgent(opts.outputAgent)) {
+    throw new ConfigApplyError(`Config output agent "${opts.outputAgent}" is retired or unsupported \u2014 cannot apply to disk.`);
+  }
+  if (isRetiredOrUnsupportedConfigAgent(config.agent)) {
+    throw new ConfigApplyError(`Config "${config.name}" uses retired or unsupported agent "${config.agent}" \u2014 cannot apply to disk.`);
+  }
+  const report = await applyConfigsWithReport([config], opts);
+  if (report.failures.length > 0) {
+    throw new ConfigApplyError(report.failures.map((failure) => failure.message).join("; "));
+  }
+  const result = report.results[0];
+  if (result)
+    return result;
+  const owned = report.skipped.find((entry) => entry.owner === SESSION_RENDERER_OWNER_ID);
+  if (owned) {
+    throw new ConfigApplyError(`Config "${config.name}" targets ${owned.path}, which is owned by ${SESSION_RENDERER_OWNER_ID}; use the Instructions session renderer.`);
+  }
+  throw new ConfigApplyError(`Config "${config.name}" has no writable targets after apply ownership checks.`);
+}
+async function applyPreparedConfig(config, opts) {
+  const selectedOutputs = opts.outputAgent ? config.outputs.filter((output) => output.agent === opts.outputAgent) : config.outputs.filter((output) => !isRetiredOrUnsupportedConfigAgent(output.agent));
+  const shouldApplyPrimary = !opts.outputAgent || config.agent === opts.outputAgent;
+  if (config.kind === "reference" || (!config.target_path || !shouldApplyPrimary) && selectedOutputs.length === 0) {
+    throw new ConfigApplyError(`Config "${config.name}" is a reference (kind=reference) and has no target_path \u2014 cannot apply to disk.`);
+  }
+  const store = opts.store ?? resolveConfigStore();
+  const contextConfigs = selectedOutputs.length > 0 || config.target_path ? await store.listConfigs() : [config];
+  if (isGeneratedOutputTarget(config, contextConfigs, opts)) {
+    throw new ConfigApplyError(`Config "${config.name}" targets a generated output path. Apply the canonical source config instead.`);
+  }
+  const outputResults = [];
+  for (const output of selectedOutputs) {
+    outputResults.push(await applyOutput(config, output, contextConfigs, opts));
+  }
+  let result;
+  if (config.target_path && shouldApplyPrimary) {
+    result = await writeConfigResult(config, config.target_path, config.content, opts);
+    result.outputs = outputResults;
+    result.changed = result.primary_changed || outputResults.some((output) => output.changed);
+    result.unresolved_template_vars = [...new Set([
+      ...result.unresolved_template_vars ?? [],
+      ...outputResults.flatMap((output) => output.unresolved_template_vars ?? [])
+    ])].sort();
+  } else {
+    result = {
+      ...outputResults[0],
+      outputs: outputResults.slice(1),
+      changed: outputResults.some((output) => output.changed)
+    };
+  }
+  if (!opts.dryRun && result.changed) {
+    await store.updateConfig(config.id, { synced_at: new Date().toISOString() });
+  }
+  return result;
+}
+async function applyOutput(config, output, contextConfigs, opts) {
+  const content = applyTransform(config, output, { configs: contextConfigs });
+  return writeConfigResult(config, output.target_path, content, opts, {
+    agent: output.agent,
+    transform: output.transform
+  });
+}
+async function applyConfigs(configs, opts = {}) {
+  const report = await applyConfigsWithReport(configs, opts);
+  if (report.failures.length > 0) {
+    throw new ConfigApplyError(report.failures.map((failure) => failure.message).join("; "));
+  }
+  return report.results;
+}
+async function applyConfigsWithReport(configs, opts = {}) {
+  const effective = { ...opts, vars: await resolveApplyVariables(opts) };
+  const prepared = prepareConfigBatch(configs, effective);
+  if (prepared.failures.length > 0) {
+    return {
+      results: [],
+      skipped: prepared.skipped,
+      failures: prepared.failures
+    };
+  }
+  const results = [];
+  const failures = [];
+  for (const config of prepared.configs) {
+    if (config.kind === "reference" || isRetiredOrUnsupportedConfigAgent(config.agent))
+      continue;
+    try {
+      results.push(await applyPreparedConfig(config, effective));
+    } catch (error) {
+      failures.push({
+        config_id: config.id,
+        config_slug: config.slug,
+        message: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  return {
+    results,
+    skipped: prepared.skipped,
+    failures
+  };
+}
+async function previewConfigs(configs, opts = {}) {
+  return applyConfigsWithReport(configs, { ...opts, dryRun: true });
+}
+function prepareConfigBatch(configs, opts) {
+  const skipped = [];
+  const outputAgent = opts.outputAgent;
+  const selectedConfigs = configs.map((config) => outputAgent ? {
+    ...config,
+    target_path: config.agent === outputAgent ? config.target_path : null,
+    outputs: config.outputs.filter((output) => output.agent === outputAgent)
+  } : config);
+  const activeConfigs = selectedConfigs.filter((config) => {
+    if (!isRetiredOrUnsupportedConfigAgent(config.agent))
+      return true;
+    for (const target of configTargets(config, opts, selectedConfigs)) {
+      skipped.push({
+        config_id: config.id,
+        config_slug: config.slug,
+        path: target.path,
+        owner: "retired-provider-config",
+        reason: `retired or unsupported provider config "${config.agent}" is excluded from profile apply`
+      });
+    }
+    return false;
+  });
+  const renderSafeConfigs = activeConfigs.filter((config) => {
+    const behavior = canonicalConfigApplyBehavior(config, opts, activeConfigs);
+    const targets = [
+      ...behavior.primary ? [{ path: behavior.primary.path, content: behavior.primary.content }] : [],
+      ...behavior.outputs.map((output) => ({ path: output.path, content: output.content }))
+    ];
+    const blocked = [...new Set(targets.flatMap((target) => wouldDestroyACredential(target.path, target.content, config.format)))].sort();
+    if (blocked.length === 0)
+      return true;
+    for (const target of targets) {
+      skipped.push({
+        config_id: config.id,
+        config_slug: config.slug,
+        path: target.path,
+        owner: "unresolved-secret-placeholder",
+        reason: `no value for ${blocked.map((name) => `{{${name}}}`).join(", ")} and the file holds something else there; writing the placeholder would overwrite a live credential`
+      });
+    }
+    return false;
+  });
+  const { configs: deduplicated, duplicates } = deduplicateEquivalentProfileConfigs(renderSafeConfigs, opts);
+  for (const duplicate of duplicates) {
+    for (const target of configTargets(duplicate, opts, activeConfigs)) {
+      skipped.push({
+        config_id: duplicate.id,
+        config_slug: duplicate.slug,
+        path: target.path,
+        owner: sessionRendererOwnsCanonicalTarget(target.path, opts) ? SESSION_RENDERER_OWNER_ID : "equivalent-profile-config",
+        reason: sessionRendererOwnsCanonicalTarget(target.path, opts) ? "provider instruction entrypoint is owned by the Instructions session renderer" : "equivalent profile config is superseded by the newer identical source"
+      });
+    }
+  }
+  const prepared = deduplicated.flatMap((config) => {
+    const behavior = canonicalConfigApplyBehavior(config, opts, activeConfigs);
+    const primaryOwned = behavior.primary ? sessionRendererOwnsCanonicalTarget(behavior.primary.path, opts) : false;
+    const outputs = config.outputs.filter((output, sourceIndex) => {
+      const canonicalOutput = behavior.outputs.find((candidate) => candidate.sourceIndex === sourceIndex);
+      const retiredOutput = isRetiredOrUnsupportedConfigAgent(output.agent);
+      const sessionOwned = sessionRendererOwnsCanonicalTarget(canonicalOutput.path, opts);
+      if (!retiredOutput && !sessionOwned)
+        return true;
+      skipped.push({
+        config_id: config.id,
+        config_slug: config.slug,
+        path: canonicalOutput.path,
+        owner: retiredOutput ? "retired-provider-config" : SESSION_RENDERER_OWNER_ID,
+        reason: retiredOutput ? `retired or unsupported provider output "${output.agent}" is excluded from profile apply` : output.agent === "antigravity" ? "project-scoped Antigravity rules are owned by the Instructions session renderer" : "provider instruction entrypoint is owned by the Instructions session renderer"
+      });
+      return false;
+    });
+    if (primaryOwned && config.target_path) {
+      skipped.push({
+        config_id: config.id,
+        config_slug: config.slug,
+        path: behavior.primary.path,
+        owner: SESSION_RENDERER_OWNER_ID,
+        reason: "provider instruction entrypoint is owned by the Instructions session renderer"
+      });
+    }
+    if (primaryOwned && outputs.length === 0)
+      return [];
+    if (!primaryOwned && outputs.length === config.outputs.length)
+      return [config];
+    return [{
+      ...config,
+      target_path: primaryOwned ? null : config.target_path,
+      outputs
+    }];
+  });
+  const failures = duplicateTargetFailures(prepared, opts);
+  return { configs: prepared, skipped, failures };
+}
+function deduplicateEquivalentProfileConfigs(configs, opts) {
+  const groups = new Map;
+  const withoutTargets = [];
+  for (const config of configs) {
+    const behavior = canonicalConfigApplyBehavior(config, opts, configs);
+    if (!behavior.primary && behavior.outputs.length === 0) {
+      withoutTargets.push(config);
+      continue;
+    }
+    groups.set(behavior.equivalenceKey, [
+      ...groups.get(behavior.equivalenceKey) ?? [],
+      config
+    ]);
+  }
+  const kept = [...withoutTargets];
+  const duplicates = [];
+  for (const group of groups.values()) {
+    const ordered = [...group].sort((left, right) => right.updated_at.localeCompare(left.updated_at) || left.slug.localeCompare(right.slug));
+    kept.push(ordered[0]);
+    duplicates.push(...ordered.slice(1));
+  }
+  const order = new Map(configs.map((config, index) => [config.id, index]));
+  kept.sort((left, right) => (order.get(left.id) ?? 0) - (order.get(right.id) ?? 0));
+  return { configs: kept, duplicates };
+}
+function canonicalConfigApplyBehavior(config, opts, contextConfigs) {
+  const primary = config.target_path ? {
+    path: canonicalApplyTargetPath(config.target_path, opts),
+    agent: config.agent,
+    content: canonicalApplyContent(config.content, opts)
+  } : null;
+  const outputs = config.outputs.map((output, sourceIndex) => ({
+    sourceIndex,
+    path: canonicalApplyTargetPath(output.target_path, opts),
+    agent: output.agent,
+    transform: output.transform,
+    content: canonicalApplyContent(applyTransform(config, output, { configs: contextConfigs }), opts)
+  })).sort((left, right) => left.path.localeCompare(right.path) || left.agent.localeCompare(right.agent) || left.transform.localeCompare(right.transform) || left.content.localeCompare(right.content));
+  const equivalenceKey = JSON.stringify({
+    kind: config.kind,
+    category: config.category,
+    primary,
+    outputs: outputs.map(({ sourceIndex: _sourceIndex, ...output }) => output)
+  });
+  return { primary, outputs, equivalenceKey };
+}
+function configTargets(config, opts, contextConfigs) {
+  const behavior = canonicalConfigApplyBehavior(config, opts, contextConfigs);
+  return [
+    ...behavior.primary ? [{ path: behavior.primary.path, owner: `${config.slug}:primary` }] : [],
+    ...behavior.outputs.map((output) => ({
+      path: output.path,
+      owner: `${config.slug}:output:${output.agent}`
+    }))
+  ];
+}
+function duplicateTargetFailures(configs, opts) {
+  const targets = new Map;
+  for (const config of configs) {
+    for (const target of configTargets(config, opts, configs)) {
+      targets.set(target.path, [
+        ...targets.get(target.path) ?? [],
+        { config, owner: target.owner }
+      ]);
+    }
+  }
+  return [...targets.entries()].filter(([, owners]) => owners.length > 1).map(([path, owners]) => ({
+    config_id: owners[0].config.id,
+    config_slug: owners[0].config.slug,
+    message: `Multiple profile writers target ${path}: ${owners.map((owner) => owner.owner).join(", ")}`
+  }));
+}
+function canonicalApplyContent(content, opts) {
+  return opts.vars ? renderMachineAwareContentPreview(content, opts.vars).content : content;
+}
+function canonicalApplyTargetPath(targetPath, opts) {
+  const renderedTargetPath = opts.vars ? renderMachineAwareContentPreview(targetPath, opts.vars).content : targetPath;
+  return normalizeTargetPath(renderedTargetPath);
+}
+function sessionRendererOwnsTarget(targetPath, opts) {
+  return sessionRendererOwnsCanonicalTarget(canonicalApplyTargetPath(targetPath, opts), opts);
+}
+function sessionRendererOwnsCanonicalTarget(normalized, opts) {
+  if (opts.allowSessionRendererOwned)
+    return false;
+  const homes = new Set([
+    getConfigHome(),
+    opts.vars?.["HOME_DIR"]
+  ].filter((home) => typeof home === "string" && home.length > 0));
+  if ([...homes].some((home) => SESSION_RENDER_OWNED_CONFIG_TARGETS.some((relativePath) => normalized === normalizeTargetPath(join2(home, ...relativePath.split("/"))))))
+    return true;
+  return sessionRenderOwnsPath(normalized);
+}
+
+export { getConfigHome, expandPath, compactPathForConfigHome, normalizeTargetPath, applyConfig, applyConfigs, applyConfigsWithReport, previewConfigs };