agentwheel 0.21.3 → 0.21.4

package/README.md

@@ -617,6 +617,18 @@ containing only `alias`, `commit` and optional `select`:
 ]
 ```
 
+To replace the complete package declaration list without resolving sources, use
+`pin --packages-file reviewed-packages.json --fleet delivery --dry-run`. The file must be a JSON
+array of workspace package entries with unique names; an empty array explicitly removes all
+package declarations. The preview prints the complete proposed config as JSON and writes nothing.
+Review it, then run the same command without `--dry-run` and with `--reason` to apply through the
+normal mutation policy, durable receipt and revision provider. This changes only desired source
+config; it does not install or remove runtime artifacts. Run normal runtime plans before installing.
+All non-package fields are preserved, as are the supplied package order, omitted defaults, metadata
+and extension fields. Package entries must pass the workspace schema. `--packages-file` cannot be
+combined with positional pins, `--pins-file` or `--select`. Existing pin forms also accept
+`--dry-run` for a non-mutating config preview.
+
 The batch cannot be combined with positional pins or `--select`. Every entry is validated before
 the config write; duplicate aliases and extra fields are refused. An omitted `select` preserves
 that package's selection; an explicit list replaces only that package's complete selection. The

package/dist/index.js

@@ -2885,7 +2885,23 @@ async function writeWorkspaceConfig(workspaceRoot, config) {
   declareMutationPath(path);
   await writeJsonAtomic(path, workspaceConfigSchema.parse(config));
 }
-async function pinConfiguredPackages(workspaceRoot, input) {
+async function pinConfiguredPackages(workspaceRoot, input, options = {}) {
+  if (options.replacePackages) {
+    const packages = z10.array(workspacePackageSchema).parse(input);
+    if (new Set(packages.map((pkg) => pkg.name)).size !== packages.length) {
+      throw new Error("Package declarations require unique aliases.");
+    }
+    const path2 = workspaceConfigPath(workspaceRoot);
+    const config2 = JSON.parse(await readFile10(path2, "utf8"));
+    workspaceConfigSchema.parse(config2);
+    config2.packages = input;
+    workspaceConfigSchema.parse(config2);
+    if (!options.dryRun) {
+      declareMutationPath(path2);
+      await writeJsonAtomic(path2, config2);
+    }
+    return config2;
+  }
   const pins = z10.array(z10.object({
     alias: z10.string().min(1),
     commit: z10.string().regex(/^[a-f0-9]{40}$/i, "Pin requires an exact 40-hex commit SHA."),
@@ -2919,8 +2935,11 @@ async function pinConfiguredPackages(workspaceRoot, input) {
     }
   }
   workspaceConfigSchema.parse(config);
-  declareMutationPath(path);
-  await writeJsonAtomic(path, config);
+  if (!options.dryRun) {
+    declareMutationPath(path);
+    await writeJsonAtomic(path, config);
+  }
+  return config;
 }
 function upsertPackage(config, entry) {
   const parsed = workspaceConfigSchema.parse(config);
@@ -21185,7 +21204,7 @@ var commandGovernance = {
   "fleet normalize": "governed-apply-or-recover",
   "cache prune": "governed-apply",
   add: "governed-always",
-  pin: "governed-always",
+  pin: "governed-unless-dry-run",
   list: "incidental-cache",
   search: "incidental-cache",
   try: "incidental-cache",
@@ -21329,14 +21348,20 @@ program.command("add").description("add a package to .agentwheel/config.json wit
   await writeWorkspaceConfig(targetRoot, upsertPackage(await readWorkspaceConfig(targetRoot), entry));
   console.log(`Added ${entry.name}. Preview: agentwheel plan - Apply: agentwheel install`);
 });
-program.command("pin").description("pin configured package aliases without resolving sources or touching runtimes").argument("[alias]", "exact configured package alias").argument("[commit]", "exact 40-hex commit SHA").option("--user", "use the user workspace", false).option("--local", "use the nearest local workspace", false).option("--fleet <id>", "use one registered named fleet").option("-t, --target-root <path>", "explicit workspace root").option("--pins-file <path>", "JSON array of {alias, commit, select?} pins in one mutation").option("--select <type/name>", "replace the complete selection (repeatable or comma-separated)", collectSelectOption).action(async (alias, commit, options) => {
+program.command("pin").description("pin configured revisions or replace package declarations without touching runtimes").argument("[alias]", "exact configured package alias").argument("[commit]", "exact 40-hex commit SHA").option("--user", "use the user workspace", false).option("--local", "use the nearest local workspace", false).option("--fleet <id>", "use one registered named fleet").option("-t, --target-root <path>", "explicit workspace root").option("--pins-file <path>", "JSON array of {alias, commit, select?} pins in one mutation").option("--packages-file <path>", "JSON array replacing the complete configured packages list").option("--dry-run", "print the complete proposed config as JSON without writing", false).option("--select <type/name>", "replace the complete selection (repeatable or comma-separated)", collectSelectOption).action(async (alias, commit, options) => {
   const workspaceRoot = await workspaceRootFromOptions(normalizeRuntimeScopeOptions(options));
-  if (options.pinsFile ? alias !== void 0 || commit !== void 0 || options.select !== void 0 : !alias || !commit) {
-    throw new Error("Choose pin <alias> <commit> [--select ...] or pin --pins-file <path>, exclusively.");
-  }
-  const pins = options.pinsFile ? JSON.parse(await readFile45(resolve44(options.pinsFile), "utf8")) : [{ alias, commit, ...options.select === void 0 ? {} : { select: options.select } }];
-  await pinConfiguredPackages(workspaceRoot, pins);
-  console.log("Pinned configured package revisions. Preview: agentwheel plan - Apply: agentwheel install");
+  const positional = alias !== void 0 || commit !== void 0 || options.select !== void 0;
+  if (options.packagesFile ? positional || options.pinsFile : options.pinsFile ? positional : !alias || !commit) {
+    throw new Error("Choose pin <alias> <commit> [--select ...], --pins-file <path>, or --packages-file <path>, exclusively.");
+  }
+  const inputFile = options.packagesFile ?? options.pinsFile;
+  const input = inputFile ? JSON.parse(await readFile45(resolve44(inputFile), "utf8")) : [{ alias, commit, ...options.select === void 0 ? {} : { select: options.select } }];
+  const config = await pinConfiguredPackages(workspaceRoot, input, {
+    dryRun: options.dryRun,
+    replacePackages: options.packagesFile !== void 0
+  });
+  if (options.dryRun) console.log(JSON.stringify(config, null, 2));
+  else console.log("Pinned configured packages. Preview: agentwheel plan - Apply: agentwheel install");
 });
 program.command("list").description("list artifacts exposed by a package source").argument("<source>", "package source").option("--driver <driver>", "source driver").option("--user", "use the user workspace", false).option("--local", "use the nearest local workspace", false).option("--fleet <id>", "use one registered named fleet").option("-t, --target-root <path>", "explicit workspace root").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).action(async (source, options) => {
   const targetRoot = await workspaceContextRootFromOptions(normalizeRuntimeScopeOptions(options));

package/openpack.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "name": "NestDevLab/agentwheel",
-  "version": "0.21.3",
+  "version": "0.21.4",
   "provides": [
     { "type": "skills", "path": "skills" }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwheel",
-  "version": "0.21.3",
+  "version": "0.21.4",
   "description": "Weave skills, rules, and instructions across every AI agent.",
   "type": "module",
   "license": "MIT",

package/skills/agentwheel/SKILL.md

@@ -5,7 +5,7 @@ allowed-tools: [Bash]
 license: MIT
 metadata:
   author: NestDevLab
-  version: "0.21.3"
+  version: "0.21.4"
 ---
 
 # agentwheel

package/skills/agentwheel-discovery/SKILL.md

@@ -5,7 +5,7 @@ allowed-tools: [Bash]
 license: MIT
 metadata:
   author: NestDevLab
-  version: "0.21.3"
+  version: "0.21.4"
 ---
 
 # Agentwheel Discovery