peaks-loop 4.1.2 → 4.1.4

package/scripts/install-skills-output-styles.mjs

@@ -0,0 +1,121 @@
+// scripts/install-skills-output-styles.mjs
+//
+// The output-style install: the style FILES, reconciled into the one IDE directory that
+// reads them. Single-target on purpose — the DISPATCH STRATEGY note below is the reason,
+// and the other two dispatch paths are named there for the comparison.
+//
+// Split out of `scripts/install-skills.mjs` (rid-043). Every line below was moved
+// VERBATIM from that file; only this header, the import block, and the `export`
+// keyword on names a sibling imports are new.
+
+import { existsSync, lstatSync, mkdirSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { reconcileCanonicalFileEntry } from './canonical-store-link.mjs';
+import { pruneBundledEntries } from './canonical-store-prune.mjs';
+import { createInstallRootValidator, resolvePackageRoot } from './install-skills-fs.mjs';
+import { createInstallResult } from './install-skills-report.mjs';
+import { resolveBundleTargetRoot } from './install-skills-ide.mjs';
+
+/**
+ * DISPATCH STRATEGY — the three paths in this file, and why they differ
+ * (D10, written down 2026-09-15).
+ *
+ * This script installs three kinds of asset, and each one resolves its target
+ * by a different rule. That was undocumented and untested; it is now
+ * documented here and each rule is stated with its reason.
+ *
+ *   1. SKILLS  (`installBundledSkillsForAllPlatforms`)
+ *      Fan out to every platform the user HAS (`isPlatformPresent`).
+ *      Reason: a skill directory is per-tool; the same skill is legitimately
+ *      wanted in several tools at once, and peaks cannot know which tool the
+ *      user will open next. Fan-out is the tenet; presence is the licence.
+ *
+ *   2. AGENTS  (`installBundledAgentsForAllPlatforms`)
+ *      Fan out to present platforms, INTERSECTED with the profiles that
+ *      declare `agentsDir`. Reason: sub-agent loaders are not a universal
+ *      concept — only 6 of 10 profiles have one. The intersection is the fan
+ *      of (1) with a capability filter, not a third rule.
+ *
+ *   3. OUTPUT STYLES (`installBundledOutputStyles`, this function)
+ *      ONE target: the IDE detected in the project root, else the legacy
+ *      `~/.claude/output-styles`. Reason: an output style is not a
+ *      per-tool asset — it is registered as THE active style for the
+ *      session by writing a single `outputStyle` key into
+ *      `~/.claude/settings.json` (`installBundledOutputStyleDefault`). A
+ *      second copy in `~/.trae/output-styles` would be a file nothing reads
+ *      and a setting no one consults; fanning it out would be storing the
+ *      same answer in ten places and reading it from one.
+ *
+ * So: (1) and (2) share one predicate and differ only by capability; (3) is
+ * deliberately single-target, and this comment is the reason the brief asked
+ * for. If a future platform needs a different rule, state it here.
+ */
+export function installBundledOutputStyles(options = {}) {
+  const packageRoot = resolvePackageRoot(options);
+  const outputStylesRoot = join(packageRoot, 'output-styles');
+
+  if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || !existsSync(outputStylesRoot)) {
+    return createInstallResult();
+  }
+
+  // Slice #011: IDE-aware dispatch — same precedence as the other two families,
+  // resolved by the same helper (`resolveBundleTargetRoot`).
+  const targetRoot = resolveBundleTargetRoot(options, {
+    profileField: 'outputStylesDir',
+    envVar: 'PEAKS_CLAUDE_OUTPUT_STYLES_DIR',
+    fallback: '.claude/output-styles'
+  });
+
+  const installed = [];
+  const skipped = [];
+  const fallbacks = [];
+  mkdirSync(targetRoot, { recursive: true });
+  const validateOutputStylesRoot = createInstallRootValidator(targetRoot, 'Peaks output styles');
+
+  // Slice 4 (`agents-canonical-store`) — same move slice 2 made for skills, with the
+  // one difference the brief calls out: a style is a FILE, so the link is a file
+  // symlink, which Windows only grants with developer mode or Administrator.
+  // `reconcileCanonicalFileEntry` is the whole policy — canonical copy, link, and the
+  // reported fallback to a real copy when the host refuses the link. The loop below
+  // no longer decides ownership, and that is deliberate: the decision it used to make
+  // was `resolve(marker.sourcePath) === resolve(sourcePath)`, a string comparison
+  // against a version-scoped package path that went false forever on the first
+  // upgrade and silently froze the style.
+  const bundledStyleNames = [];
+  for (const outputStyleName of readdirSync(outputStylesRoot)) {
+    const sourcePath = join(outputStylesRoot, outputStyleName);
+    if (!lstatSync(sourcePath).isFile() || !outputStyleName.endsWith('.md')) continue;
+    bundledStyleNames.push(outputStyleName);
+
+    validateOutputStylesRoot();
+    const reconciled = reconcileCanonicalFileEntry({
+      kind: 'output-styles',
+      name: outputStyleName,
+      sourcePath,
+      linkPath: join(targetRoot, outputStyleName),
+      createFileLink: options.createFileLink
+    });
+    validateOutputStylesRoot();
+
+    if (reconciled.linkAction === 'skipped') {
+      skipped.push(outputStyleName);
+      continue;
+    }
+    installed.push(outputStyleName);
+    if (reconciled.fallback !== null) {
+      fallbacks.push({ name: outputStyleName, ...reconciled.fallback });
+    }
+  }
+
+  // The delete half, for the same reason skills have one: the loop above only ever
+  // adds. A style removed from the package used to leave its canonical copy, its IDE
+  // link and both sidecars behind forever.
+  const { pruned } = pruneBundledEntries({
+    kind: 'output-styles',
+    keepNames: bundledStyleNames,
+    linkDirs: [targetRoot]
+  });
+
+  return { installed, skipped, pruned, fallbacks };
+}

package/scripts/install-skills-report.mjs

@@ -0,0 +1,42 @@
+// scripts/install-skills-report.mjs
+//
+// A fallback is not a failure but must not LOOK like one, and a `skipped` entry is a
+// half migration that must not be invisible. Both are reported here, and the shared
+// empty result shape lives beside them.
+//
+// Split out of `scripts/install-skills.mjs` (rid-043). Every line below was moved
+// VERBATIM from that file; only this header, the import block, and the `export`
+// keyword on names a sibling imports are new.
+
+export function createInstallResult() {
+  return { installed: [], skipped: [], pruned: [], fallbacks: [] };
+}
+
+/**
+ * A fallback is not a failure — but it must never LOOK like a plain success. The
+ * entry is a real copy instead of a link, and the postinstall says so, naming each
+ * one. Silence here would be the same shape as the defect this slice fixes: an
+ * outcome nobody can observe from the outside.
+ */
+export function reportCopyFallbacks(label, fallbacks) {
+  if (fallbacks.length === 0) return;
+  process.stderr.write(
+    `Peaks ${label}: ${fallbacks.map((entry) => entry.name).join(', ')} ` +
+      'installed as REAL COPIES because this host refused a symlink ' +
+      `(${fallbacks[0].code ?? 'no code returned'})\n`
+  );
+}
+
+/**
+ * The other half of the same rule, for the other bucket. A `skipped` entry means the
+ * canonical copy WAS written and the IDE entry was NOT — a half migration. Whatever the
+ * cause (a file the user authored, or an entry whose sidecar names a second live
+ * installation), it must not be invisible: the whole defect this slice fixes was an
+ * outcome nobody could observe from outside.
+ */
+export function reportLeftAlone(label, skipped) {
+  if (skipped.length === 0) return;
+  process.stderr.write(
+    `Peaks ${label}: left alone, not peaks-loop's to replace: ${skipped.join(', ')}\n`
+  );
+}

package/scripts/install-skills-user-config.mjs

@@ -0,0 +1,198 @@
+// scripts/install-skills-user-config.mjs
+//
+// The `~/.peaks/config.json` install: the defaults, the merge that never overwrites a
+// key the user wrote, the path validation that keeps the write inside the user root,
+// and the atomic write. Includes the record of the DELETED project-config sibling, so
+// the next reader does not re-add it.
+//
+// Split out of `scripts/install-skills.mjs` (rid-043). Every line below was moved
+// VERBATIM from that file; only this header, the import block, and the `export`
+// keyword on names a sibling imports are new.
+
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+import {
+  getPathStats,
+  isInsidePath,
+  isPlainObject,
+  readFileSafely,
+  resolvePackageRoot,
+  writeFileAtomically
+} from './install-skills-fs.mjs';
+
+export function readPackageVersion(packageRoot = resolvePackageRoot()) {
+  const packageJson = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+  if (typeof packageJson.version !== 'string' || packageJson.version.length === 0) {
+    throw new Error('package.json version must be a non-empty string');
+  }
+
+  return packageJson.version;
+}
+
+export function createConfigDefaults(packageRoot) {
+  return {
+    version: readPackageVersion(packageRoot),
+    currentWorkspace: null,
+    workspaces: [],
+    language: 'en',
+    economyMode: true,
+    swarmMode: true,
+    tokens: {},
+    proxy: {}
+  };
+}
+
+export function createConfigResult(overrides = {}) {
+  return { created: false, updated: false, skipped: false, ...overrides };
+}
+
+export function mergeMissingConfigValues(existing, defaults) {
+  return Object.entries(defaults).reduce(
+    (next, [key, defaultValue]) => {
+      if (!(key in next)) {
+        return { ...next, [key]: defaultValue };
+      }
+
+      const existingValue = next[key];
+      if (isPlainObject(existingValue) && isPlainObject(defaultValue)) {
+        return { ...next, [key]: mergeMissingConfigValues(existingValue, defaultValue) };
+      }
+
+      return next;
+    },
+    { ...existing }
+  );
+}
+
+export function readConfigFile(configPath, label) {
+  if (!existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(
+      readFileSafely(configPath, `${label} config path changed during read`)
+    );
+    if (!isPlainObject(parsed)) {
+      throw new Error(`${label} config must contain a JSON object`);
+    }
+
+    return parsed;
+  } catch (error) {
+    const message =
+      error instanceof SyntaxError
+        ? `${label} config must contain valid JSON`
+        : error instanceof Error
+          ? error.message
+          : String(error);
+    throw new Error(message);
+  }
+}
+
+export function validateConfigPath(root, peaksRoot, configPath, label) {
+  const rootReal = realpathSync(root);
+  const peaksStats = lstatSync(peaksRoot);
+  const peaksReal = realpathSync(peaksRoot);
+  if (
+    !peaksStats.isDirectory() ||
+    peaksStats.isSymbolicLink() ||
+    peaksReal !== resolve(rootReal, '.peaks')
+  ) {
+    throw new Error(`${label} config path must stay inside the ${label.toLowerCase()} root`);
+  }
+
+  const configStats = getPathStats(configPath);
+  if (configStats?.isSymbolicLink()) {
+    throw new Error(`${label} config path must not be a symlink`);
+  }
+  if (configStats && !configStats.isFile()) {
+    throw new Error(`${label} config path must be a file`);
+  }
+  if (configStats) {
+    if (configStats.nlink !== 1) {
+      throw new Error(`${label} config path must not be hardlinked`);
+    }
+    const configReal = realpathSync(configPath);
+    if (!isInsidePath(configReal, rootReal) || !isInsidePath(configReal, peaksReal)) {
+      throw new Error(`${label} config path must stay inside the ${label.toLowerCase()} root`);
+    }
+  }
+}
+
+export function validateUserConfigPaths(userRoot, peaksRoot, configPath) {
+  validateConfigPath(userRoot, peaksRoot, configPath, 'User');
+}
+
+export function writeUserConfig(userRoot, peaksRoot, configPath, content) {
+  writeFileAtomically(configPath, content, 'User config path changed during write', () =>
+    validateUserConfigPaths(userRoot, peaksRoot, configPath)
+  );
+}
+
+export function writeMergedConfig(configPath, label, defaults, writeConfig) {
+  const existing = readConfigFile(configPath, label);
+  const next = {
+    ...(existing === null ? defaults : mergeMissingConfigValues(existing, defaults)),
+    version: defaults.version
+  };
+  const currentJson = existing === null ? null : `${JSON.stringify(existing, null, 2)}\n`;
+  const nextJson = `${JSON.stringify(next, null, 2)}\n`;
+
+  if (currentJson === nextJson) {
+    return createConfigResult();
+  }
+
+  writeConfig(nextJson);
+  return createConfigResult(existing === null ? { created: true } : { updated: true });
+}
+
+export function installUserConfig(options = {}) {
+  if (
+    process.env.PEAKS_SKIP_SKILL_INSTALL === '1' ||
+    process.env.PEAKS_SKIP_USER_CONFIG_INSTALL === '1'
+  ) {
+    return createConfigResult({ skipped: true });
+  }
+
+  const userRoot = resolve(options.userRoot ?? homedir());
+  const peaksRoot = resolve(userRoot, '.peaks');
+  const configPath = resolve(peaksRoot, 'config.json');
+  if (!isInsidePath(configPath, userRoot)) {
+    throw new Error('User config path must stay inside the user root');
+  }
+
+  if (!existsSync(peaksRoot)) {
+    mkdirSync(peaksRoot, { recursive: true });
+  }
+  validateUserConfigPaths(userRoot, peaksRoot, configPath);
+
+  return writeMergedConfig(
+    configPath,
+    'User',
+    createConfigDefaults(options.packageRoot),
+    (content) => writeUserConfig(userRoot, peaksRoot, configPath, content)
+  );
+}
+
+/*
+ * D11 (2026-09-15): `installProjectConfig` — plus its two private helpers
+ * `writeProjectConfig` and `validateProjectConfigPaths` — was DELETED here.
+ *
+ * It was dead: definition + `export`, and zero call sites in the whole repo
+ * (verified by a repo-wide grep for the identifier, excluding node_modules
+ * and dist). The `PEAKS_SKIP_PROJECT_CONFIG_INSTALL` env var existed only to
+ * disable it.
+ *
+ * Deleted rather than wired, because wiring it would be the bigger defect:
+ * `npm i -g peaks-loop` executed from inside a user's repo would write
+ * `<project>/.peaks/config.json` as a side effect of a GLOBAL install. The
+ * project-level config is owned by `peaks workspace init` and the config
+ * service at runtime; a postinstall reaching into the current working
+ * directory to create project state is the opposite of the "minimal user
+ * operation" tenet — an operation the user never asked for.
+ *
+ * The user-config sibling (`installUserConfig`, below) is live and is what
+ * the postinstall actually calls.
+ */