joycraft 0.7.16 → 0.7.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -42,7 +42,7 @@ cd /path/to/your/project
42
42
  npx joycraft@latest update
43
43
  ```
44
44
 
45
- Answer a few questions — which harnesses to install, whether to commit them, and (with Claude Code) whether to turn off auto-memory for this project — and `update` does the rest: detects your stack, writes `AGENTS.md`/`CLAUDE.md` with your real build/test commands, installs the skills. On later runs, unmodified vendor files refresh while customizations are preserved for review.
45
+ Answer a few questions — which harnesses to install, whether to commit them, and (with Claude Code) whether to turn off auto-memory for this project — and `update` does the rest: detects your stack, writes `AGENTS.md`/`CLAUDE.md` with your real build/test commands, installs the skills. On later runs, Joycraft's skills and templates refresh to the latest version (an edited copy is saved first), and your own files stay untouched.
46
46
 
47
47
  `npm install -g joycraft` if you'd rather have the command on your PATH; `npx` works without it. Every step from install to first shipped feature: [Setup walkthrough](docs/guides/setup-walkthrough.md).
48
48
 
@@ -66,7 +66,7 @@ Brainstorming first? `/joycraft-interview`. Fixing a bug? `/joycraft-bugfix`. Th
66
66
  npx joycraft@latest update
67
67
  ```
68
68
 
69
- Run this from the project root. In a fresh interactive project it asks which harnesses to install. In CI or another unattended fresh project, provide an explicit selection, for example `--harnesses codex --non-interactive`. On an existing project it reads the shared or private installation manifest and preserves the selected harnesses, local content, unrelated configuration, and unknown state fields. `--yes` applies safe changes while preserving customized files; it is not blanket permission to overwrite them. Use `--preview` to review the actual plan, `--replace-customized <paths...>` for reviewed replacements, and `--repair <paths...>` for explicitly restoring missing managed files. Details, policies, bridge behavior, and exit codes are in [Upgrading](docs/guides/upgrading.md).
69
+ Run this from the project root. In a fresh interactive project it asks which harnesses to install. In CI or another unattended fresh project, provide an explicit selection, for example `--harnesses codex --non-interactive`. On an existing project it reads the shared or private installation manifest and preserves the selected harnesses, local content, unrelated configuration, and unknown state fields. Your own files (`CLAUDE.md`, `AGENTS.md`, `deny-patterns.txt`, your settings) are never changed; an edited Joycraft skill or template is replaced with the latest version after your copy is saved under `docs/.joycraft/local/replaced/`. `--yes` follows the same rules. Use `--preview` to review the actual plan, `--replace-customized <paths...>` to reset one of your own files to Joycraft's default, and `--repair <paths...>` for explicitly restoring missing managed files. Details, policies, bridge behavior, and exit codes are in [Upgrading](docs/guides/upgrading.md).
70
70
 
71
71
  `init` and `upgrade` remain supported aliases into the same update engine. `init` is the friendly fresh-install entry point; `upgrade` keeps older automation working. If npm fails with `ETARGET` before Joycraft starts, retry with an online npm metadata refresh:
72
72
 
@@ -524,6 +524,16 @@ var createOnce = (path) => ({
524
524
  active: true,
525
525
  installable: false
526
526
  });
527
+ var createOnceWithContent = (path, harness, content, options = {}) => ({
528
+ ...vendor(path, harness, content, options),
529
+ kind: "create-once"
530
+ });
531
+ var DENY_PATTERNS_PATH = ".claude/hooks/joycraft/deny-patterns.txt";
532
+ var EXAMPLE_EVAL_TEMPLATE_KEY = "evals/example-task.json";
533
+ var USER_OWNED_VENDOR_PATHS = [
534
+ DENY_PATTERNS_PATH,
535
+ `docs/templates/${EXAMPLE_EVAL_TEMPLATE_KEY}`
536
+ ];
527
537
  var patch = (path, harness, ownedKey, ownedRegion) => ({
528
538
  path,
529
539
  harness,
@@ -542,6 +552,7 @@ var TEMPLATE_HARNESS_GATES = {
542
552
  function templateEntries(templates, selected2, gates = TEMPLATE_HARNESS_GATES) {
543
553
  return Object.entries(templates).flatMap(([path, content]) => {
544
554
  const gate = Object.prototype.hasOwnProperty.call(gates, path) ? gates[path] : void 0;
555
+ if (path === EXAMPLE_EVAL_TEMPLATE_KEY) return [createOnceWithContent(`docs/templates/${path}`, "shared", content)];
545
556
  if (!gate) return [vendor(`docs/templates/${path}`, "shared", content)];
546
557
  const owner = HARNESSES.find((harness) => gate.includes(harness) && selected2.includes(harness));
547
558
  return owner ? [vendor(`docs/templates/${path}`, owner, content)] : [];
@@ -566,7 +577,7 @@ function getBundleInventory(selection = HARNESSES) {
566
577
  entries.push(...mapVendorFiles("claude", ".claude/skills", SKILLS));
567
578
  entries.push(
568
579
  vendor(".claude/hooks/joycraft/block-dangerous.sh", "claude", generateHookScript(), { executable: true, mode: 493 }),
569
- vendor(".claude/hooks/joycraft/deny-patterns.txt", "claude", generateDenyPatternsFile(), { executable: false }),
580
+ createOnceWithContent(DENY_PATTERNS_PATH, "claude", generateDenyPatternsFile(), { executable: false }),
570
581
  vendor(".claude/hooks/joycraft-version-check.mjs", "claude", generateClaudeSessionStartAdapter(), { executable: true, mode: 493 }),
571
582
  patch(".claude/settings.json", "claude", void 0, "hooks.SessionStart[command=node .claude/hooks/joycraft-version-check.mjs]"),
572
583
  patch(".claude/settings.json", "claude", void 0, "hooks.PreToolUse[command=.claude/hooks/joycraft/block-dangerous.sh]"),
@@ -888,6 +899,7 @@ function createUpdatePlan(input) {
888
899
  const actions = [];
889
900
  const groups = /* @__PURE__ */ new Map();
890
901
  const knownPaths = /* @__PURE__ */ new Set();
902
+ const backupDirectory = options.backupDirectory ?? `docs/.joycraft/local/replaced/${options.targetVersion ?? input.manifest.targetVersion}`;
891
903
  for (const entry of input.inventory) {
892
904
  knownPaths.add(entry.path);
893
905
  if (entry.kind === "create-once" && entry.content === void 0 || !entry.active || !entry.installable || entry.kind === "vendor" && entry.content === void 0) continue;
@@ -976,6 +988,7 @@ function createUpdatePlan(input) {
976
988
  const targetEqualsBase = baselineHash !== void 0 && targetHash === baselineHash;
977
989
  let kind;
978
990
  let reason;
991
+ let untouchedCreateOnce = false;
979
992
  if (currentContent === void 0) {
980
993
  if (verified) {
981
994
  kind = "preserve";
@@ -990,6 +1003,7 @@ function createUpdatePlan(input) {
990
1003
  } else if (old?.kind === "create-once" && !explicitReplacement(options, group.path)) {
991
1004
  kind = "preserve";
992
1005
  reason = "Create-once document is user-owned after its first creation; preserve local content.";
1006
+ untouchedCreateOnce = old.vendorHash !== "" && currentHash === old.vendorHash;
993
1007
  } else if (currentEqualsTarget) {
994
1008
  kind = old && verified ? "reconcile" : "adopt";
995
1009
  reason = kind === "reconcile" ? "Current bytes already equal target; reconcile manifest metadata." : "Exact trusted target match establishes vendor ownership.";
@@ -999,9 +1013,16 @@ function createUpdatePlan(input) {
999
1013
  } else if ((options.forceCustomized ?? []).includes(group.path)) {
1000
1014
  kind = "replace";
1001
1015
  reason = "Scoped init force selected this known customized path.";
1016
+ } else if (first.kind === "create-once" && !explicitReplacement(options, group.path)) {
1017
+ kind = "preserve";
1018
+ reason = "User-owned file; Joycraft does not change it after creating it.";
1019
+ if (old) nextManifest.files[group.path] = { ...old, kind: "create-once" };
1002
1020
  } else if (targetEqualsBase) {
1003
1021
  kind = "preserve";
1004
1022
  reason = "Vendor target is unchanged; preserve the local-only edit.";
1023
+ } else if (first.kind === "vendor") {
1024
+ kind = "replace";
1025
+ reason = "Joycraft has a newer version of this edited file; the edited copy is saved as a backup.";
1005
1026
  } else if (verified) {
1006
1027
  kind = "conflict";
1007
1028
  reason = "Current customization and target vendor content both differ from the verified base.";
@@ -1014,6 +1035,7 @@ function createUpdatePlan(input) {
1014
1035
  reason = "Explicit replacement selected for this customized path.";
1015
1036
  }
1016
1037
  const action = actionBase(group.path, kind, reason, currentContent, target, first.mode);
1038
+ if (untouchedCreateOnce && kind === "preserve") action.nonActionable = true;
1017
1039
  if (target !== void 0 && ["replace", "create", "adopt", "conflict"].includes(kind)) action.content = bytes(target);
1018
1040
  action.selected = selected(options, group.path, kind);
1019
1041
  if (kind === "preserve" && currentContent === void 0 && verified && options.repair?.includes(group.path)) {
@@ -1027,6 +1049,16 @@ function createUpdatePlan(input) {
1027
1049
  }
1028
1050
  if (kind === "conflict" && currentContent !== void 0 && target !== void 0) action.diff = diff(group.path, currentContent, target);
1029
1051
  if (first.kind === "config-patch") action.patch = { ...first.ownedKey ? { ownedKey: first.ownedKey } : {}, ...first.ownedRegion ? { ownedRegion: first.ownedRegion } : {} };
1052
+ const overwritesEdits = currentContent !== void 0 && first.kind !== "config-patch" && !currentEqualsBase && !currentEqualsTarget && action.selected && (action.kind === "replace" || action.kind === "conflict" && action.resolution === "replace");
1053
+ if (overwritesEdits) {
1054
+ action.backupPath = `${backupDirectory}/${group.path}.bak`;
1055
+ add({
1056
+ ...actionBase(action.backupPath, "create", `Edited copy of ${group.path}, saved before Joycraft replaced it.`, void 0, currentContent, void 0),
1057
+ selected: true,
1058
+ content: bytes(currentContent),
1059
+ backupOf: group.path
1060
+ });
1061
+ }
1030
1062
  add(action);
1031
1063
  if (action.selected && ["replace", "create", "adopt", "repair", "reconcile"].includes(action.kind)) addFile(nextManifest, group.path, first, targetHash, options.targetVersion ?? input.manifest.targetVersion);
1032
1064
  if (action.selected && action.kind === "conflict" && action.resolution === "replace") addFile(nextManifest, group.path, first, targetHash, options.targetVersion ?? input.manifest.targetVersion);
@@ -1110,6 +1142,7 @@ var LOCK_RELATIVE = `${LOCAL_DIR}/update.lock`;
1110
1142
  var JOURNAL_RELATIVE = `${LOCAL_DIR}/update-journal.json`;
1111
1143
  var BACKUPS_RELATIVE = `${LOCAL_DIR}/backups`;
1112
1144
  var LAST_SUCCESSFUL_RELATIVE = `${LOCAL_DIR}/last-successful.json`;
1145
+ var REPLACED_RELATIVE = `${LOCAL_DIR}/replaced`;
1113
1146
  var TransactionConflictError = class extends Error {
1114
1147
  conflictPath;
1115
1148
  constructor(message, conflictPath) {
@@ -1261,6 +1294,7 @@ function profileFor(plan, options) {
1261
1294
  return plan.nextManifest.profile;
1262
1295
  }
1263
1296
  function isControlPath(relativePath, profile) {
1297
+ if (relativePath.startsWith(`${REPLACED_RELATIVE}/`)) return false;
1264
1298
  const controls = [
1265
1299
  // Both authority locations are transaction control paths regardless of
1266
1300
  // the destination profile. A private transaction must not be able to
@@ -2855,10 +2889,7 @@ function materializeDocuments(input, existingSkills) {
2855
2889
  const exists = regularFile(input.root, entry.path);
2856
2890
  const recorded = input.manifest.files[entry.path] !== void 0;
2857
2891
  const forceKnown = input.force === true && KNOWN_GENERATED_DOCUMENTS.has(entry.path);
2858
- if (entry.content !== void 0) {
2859
- if (!exists || forceKnown) return [entry];
2860
- return [];
2861
- }
2892
+ if (entry.content !== void 0) return [entry];
2862
2893
  const content = generatorContent(
2863
2894
  input.root,
2864
2895
  entry.path,
@@ -3241,6 +3272,9 @@ function evaluateAutoSafeEligibility(input) {
3241
3272
  reject("The update plan changes user configuration.");
3242
3273
  }
3243
3274
  if ((input.replaceCustomized?.length ?? 0) > 0) reject("Customized replacements require an explicit update.");
3275
+ if (input.plan.actions.some((action) => action.selected && action.backupPath !== void 0)) {
3276
+ reject("Replacing edited files requires an explicit update.");
3277
+ }
3244
3278
  if ((input.repair?.length ?? 0) > 0) reject("Repairs require an explicit update.");
3245
3279
  if (input.migration) reject("Migrations require an explicit update.");
3246
3280
  if (input.legacyBridge) reject("Legacy bridge adoption requires an explicit update.");
@@ -3532,11 +3566,20 @@ function localSettingsFromAdoption(root, entries, bundle, profile) {
3532
3566
  return { manifest: adopted.manifest, localSettings: adopted.localSettings, conflicts: adopted.conflicts };
3533
3567
  }
3534
3568
  function pathsForOutcome(plan) {
3535
- const applied = plan.actions.filter((action) => action.selected && ["replace", "create", "repair", "delete", "conflict"].includes(action.kind)).map((action) => action.path);
3569
+ const applied = plan.actions.filter((action) => action.selected && !action.backupOf && ["replace", "create", "repair", "delete", "conflict"].includes(action.kind)).map((action) => action.path);
3570
+ const replaced = plan.actions.filter((action) => action.selected && action.backupPath !== void 0).map((action) => ({ path: action.path, backup: action.backupPath }));
3536
3571
  const resolved = new Set(plan.actions.filter((action) => action.kind === "conflict" && action.selected && action.resolution === "replace").map((action) => action.path));
3537
3572
  const preserved = plan.preserved.filter((entry) => !resolved.has(entry.path)).filter((entry) => !plan.actions.some((action) => action.path === entry.path && action.nonActionable === true)).map((entry) => entry.path);
3538
3573
  const conflicts = plan.conflicts.filter((action) => !resolved.has(action.path)).map((action) => action.path);
3539
- return { applied: [...new Set(applied)], preserved: [...new Set(preserved)], conflicts: [...new Set(conflicts)] };
3574
+ return { applied: [...new Set(applied)], preserved: [...new Set(preserved)], conflicts: [...new Set(conflicts)], replaced };
3575
+ }
3576
+ function backupDirectoryFor(root, now = /* @__PURE__ */ new Date()) {
3577
+ const pad = (value) => String(value).padStart(2, "0");
3578
+ const stamp = `${now.getUTCFullYear()}${pad(now.getUTCMonth() + 1)}${pad(now.getUTCDate())}-${pad(now.getUTCHours())}${pad(now.getUTCMinutes())}${pad(now.getUTCSeconds())}`;
3579
+ const base = `docs/.joycraft/local/replaced/${stamp}`;
3580
+ let candidate = base;
3581
+ for (let suffix = 2; existsSync8(join10(root, ...candidate.split("/"))); suffix += 1) candidate = `${base}-${suffix}`;
3582
+ return candidate;
3540
3583
  }
3541
3584
  function setupPatchAction(operation) {
3542
3585
  return {
@@ -3771,7 +3814,8 @@ async function update(dir, options = {}) {
3771
3814
  replaceCustomized: [...new Set(replaceCustomized)],
3772
3815
  forceCustomized: [...new Set(forceCustomized)],
3773
3816
  repair: options.repair,
3774
- baseManifestDigest: existingManifest ? void 0 : null
3817
+ baseManifestDigest: existingManifest ? void 0 : null,
3818
+ backupDirectory: backupDirectoryFor(root)
3775
3819
  }
3776
3820
  });
3777
3821
  plan.diagnostics.push(...materialized.diagnostics.map((diagnostic) => /settings\.json is malformed/i.test(diagnostic) && !/fix the json/i.test(diagnostic) ? `${diagnostic} Fix the JSON before retrying.` : diagnostic));
@@ -3811,12 +3855,13 @@ async function update(dir, options = {}) {
3811
3855
  authorityTransition: authorityTransition !== void 0
3812
3856
  });
3813
3857
  if (!eligibility.eligible) {
3814
- return outcome(selected2.conflicts.length > 0 ? "conflict" : "invalid", {
3858
+ const needsReview = [.../* @__PURE__ */ new Set([...selected2.conflicts, ...selected2.replaced.map((entry) => entry.path)])];
3859
+ return outcome(needsReview.length > 0 ? "conflict" : "invalid", {
3815
3860
  targetVersion: bundle.version,
3816
3861
  profile: authority.profile,
3817
3862
  harnesses,
3818
3863
  preserved: selected2.preserved,
3819
- conflicts: selected2.conflicts,
3864
+ conflicts: needsReview,
3820
3865
  diagnostics: [...plan.diagnostics, ...eligibility.diagnostics],
3821
3866
  plan,
3822
3867
  localSettings,
@@ -3834,6 +3879,7 @@ async function update(dir, options = {}) {
3834
3879
  applied: [],
3835
3880
  preserved: selected2.preserved,
3836
3881
  conflicts: selected2.conflicts,
3882
+ replaced: selected2.replaced,
3837
3883
  diagnostics: plan.diagnostics,
3838
3884
  plan,
3839
3885
  localSettings,
@@ -3899,6 +3945,7 @@ async function update(dir, options = {}) {
3899
3945
  applied: actualApplied,
3900
3946
  preserved: selected2.preserved,
3901
3947
  conflicts: [.../* @__PURE__ */ new Set([...selected2.conflicts, ...transaction.conflicts])],
3948
+ replaced: transaction.status === "applied" ? selected2.replaced : [],
3902
3949
  diagnostics,
3903
3950
  transaction,
3904
3951
  plan,
@@ -3919,24 +3966,34 @@ function formatUpdateOutcome(result, json = false) {
3919
3966
  applied: result.applied,
3920
3967
  preserved: result.preserved,
3921
3968
  conflicts: result.conflicts,
3969
+ replaced: result.replaced ?? [],
3922
3970
  diagnostics: result.diagnostics,
3923
3971
  registry: result.registry,
3924
3972
  existingSkills: result.existingSkills,
3925
3973
  transaction: result.transaction
3926
3974
  });
3927
3975
  }
3928
- const lines = [`Joycraft update: ${result.status}.`];
3929
- if (result.targetVersion) lines.push(` Target: ${result.targetVersion}`);
3976
+ const target = result.targetVersion;
3977
+ const headline = result.status === "applied" && target ? `Joycraft updated to ${target}.` : (result.status === "noop" || result.status === "preserved") && target ? `Joycraft is up to date (${target}).` : result.status === "conflict" ? "Joycraft update needs your review." : `Joycraft update: ${result.status}.`;
3978
+ const lines = [headline];
3979
+ if (target && !headline.includes(target)) lines.push(` Target: ${target}`);
3930
3980
  if (result.applied.length) lines.push(` Applied: ${result.applied.length}`);
3931
- if (result.preserved.length) lines.push(` Preserved customizations: ${result.preserved.join(", ")}`);
3932
- if (result.conflicts.length) lines.push(` Pending conflicts: ${result.conflicts.join(", ")}`);
3981
+ const replaced = result.replaced ?? [];
3982
+ if (replaced.length) {
3983
+ const first = replaced[0];
3984
+ const directory = first.backup.slice(0, first.backup.length - `${first.path}.bak`.length);
3985
+ lines.push(` Replaced your edited copies (saved in ${directory}): ${replaced.map((entry) => entry.path).join(", ")}`);
3986
+ }
3987
+ if (result.preserved.length) lines.push(` Kept your versions: ${result.preserved.join(", ")}`);
3988
+ if (result.conflicts.length) lines.push(` Needs review: ${result.conflicts.join(", ")}`);
3933
3989
  for (const diagnostic of result.diagnostics) lines.push(` \u26A0 ${diagnostic}`);
3934
3990
  return lines.join("\n");
3935
3991
  }
3936
3992
 
3937
3993
  export {
3938
3994
  updateStatusExitCode,
3995
+ backupDirectoryFor,
3939
3996
  update,
3940
3997
  formatUpdateOutcome
3941
3998
  };
3942
- //# sourceMappingURL=chunk-GTP7Z52K.js.map
3999
+ //# sourceMappingURL=chunk-YLWBDXF4.js.map