@anhlp/alp-cli 0.0.1-beta.7 → 0.0.1-beta.8

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/src/daemon.js CHANGED
@@ -2,7 +2,7 @@ import { access } from 'node:fs/promises';
2
2
  import path from 'node:path';
3
3
  import { installedProgram, installService, serviceFor, uninstallService } from '@anhlp/alp-client/service';
4
4
  import { holdDaemon, startDaemon } from '@anhlp/alp-client/supervise';
5
- import { alpHome, connect, lockAlive, readLock, withDaemonLifecycle } from '@anhlp/alp-client/index';
5
+ import { alpHome, connect, daemonStartTimeoutMs, lockAlive, readLock, withDaemonLifecycle } from '@anhlp/alp-client/index';
6
6
  import { scrubText } from '@anhlp/alp-core/log';
7
7
  import { UsageError } from './usage.js';
8
8
  import { DAEMON_ENTRY } from './paths.js';
@@ -16,9 +16,9 @@ async function built() {
16
16
  }
17
17
  }
18
18
 
19
- /** Waits until an alpd for this home is ready; returns its socket. */
19
+ /** Waits until an alpd for this home is ready; returns its socket. Default wait: ALP_DAEMON_START_TIMEOUT_MS, else 60 s. */
20
20
 
21
- async function ready(timeoutMs = 15_000) {
21
+ async function ready(timeoutMs = daemonStartTimeoutMs()) {
22
22
  const deadline = Date.now() + timeoutMs;
23
23
  while (Date.now() < deadline) {
24
24
  const lock = await readLock(alpHome());
package/src/interfaces.js CHANGED
@@ -8,6 +8,7 @@ import { UsageError } from './usage.js';
8
8
  import { built, start, running } from './daemon.js';
9
9
  import { DAEMON_ENTRY, distributionEntry } from './paths.js';
10
10
  import { entryCommand } from '@anhlp/alp-core/packaged';
11
+ import { isAgentProcess } from '@anhlp/alp-core/tasks';
11
12
  import { runRole } from './roles.js';
12
13
  import { alpWebEntry, alpWebScript, isWebClaimed, isWebReady, refusal, stopPreRenamePaseo, stopWebService, webOwner } from './web-service.js';
13
14
 
@@ -186,6 +187,9 @@ async function serveWeb(home, entry) {
186
187
  }
187
188
 
188
189
  async function webCommand(args) {
190
+ // alp web prints, rotates and pairs with the user's own secrets (t-1c59): a process an ALP agent
191
+ // started is refused before anything is read, stopped or printed.
192
+ if (isAgentProcess()) throw new Error('alp web is the user\'s: it prints and rotates the user\'s credential; this process was started by an ALP agent (ALP_AGENT_SESSION is set)');
189
193
  if (args[0] === 'pair') return pairCommand(args.slice(1));
190
194
  if (args[0] === 'rotate') return rotateCommand(args.slice(1));
191
195
  // alp-web itself in this process; its own options (--service, --rotate, --project DIR) follow.
package/src/library.js CHANGED
@@ -4,15 +4,26 @@ import { parseArgs } from 'node:util';
4
4
  import { seedLibrary } from '@anhlp/alp-core/library';
5
5
  import { libraryEntries } from '@anhlp/alp-core/resolver';
6
6
  import { listTeams, resolveTeam } from '@anhlp/alp-core/teams';
7
- import { deleteEntry, duplicateEntry, getEntry, renameEntry, saveEntry } from '@anhlp/alp-core/library-edit';
7
+ import { deleteEntry, duplicateEntry, getEntry, listRetiredSkills, renameEntry, restoreSkill, saveEntry, withSkillName } from '@anhlp/alp-core/library-edit';
8
8
  import { testEntry } from '@anhlp/alp-client/library-test';
9
+ import { formatValidation, validateSkill } from '@anhlp/alp-core/skill-validate';
10
+ import { installPack, listPacks, packStatus } from '@anhlp/alp-core/packs';
9
11
  import { alpHome } from '@anhlp/alp-client/index';
10
12
  import { UsageError } from './usage.js';
11
13
  import { taskProject } from './tasks.js';
12
14
 
13
15
  async function libraryCommand(kind, args) {
14
- const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { project: { type: 'string' }, json: { type: 'boolean' } } });
16
+ const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { project: { type: 'string' }, json: { type: 'boolean' }, ...(kind === 'skills' ? { retired: { type: 'boolean' } } : {}) } });
15
17
  if (positionals.length) throw new UsageError();
18
+ if (values.retired) {
19
+ if (values.project !== undefined) throw new UsageError();
20
+ const rows = await listRetiredSkills({ library: alpHome() });
21
+ if (values.json) { console.log(JSON.stringify(rows)); return; }
22
+ if (!rows.length) { console.log(`No retired skills in ${path.join(alpHome(), 'retired-skills')}`); return; }
23
+ const width = Math.max(...rows.map(row => row.name.length));
24
+ for (const row of rows) console.log(`${row.name.padEnd(width)} ${row.retiredAt} ${row.roles === null ? 'roles not recorded' : `roles: ${row.roles.join(', ') || 'none'}`}${row.agent ? `; by ${row.agent}` : ''}${row.invalid ? `; warning: invalid retired metadata: ${row.invalid}` : ''} ${row.directory}`);
25
+ return;
26
+ }
16
27
  if (kind === 'providers') await seedLibrary(alpHome());
17
28
  // Outside a project only the built-ins and the library apply.
18
29
  const root = path.resolve(values.project ?? process.cwd());
@@ -57,12 +68,11 @@ const EDIT_OPTIONS = {
57
68
  'member-thinking': { type: 'string', multiple: true }, delegate: { type: 'string', multiple: true }, 'max-peers': { type: 'string' },
58
69
  supervisor: { type: 'string' }, 'supervisor-model': { type: 'string' }, 'supervisor-thinking': { type: 'string' }, 'no-supervisor': { type: 'boolean' }, rules: { type: 'string' },
59
70
  // skill, mcp, hook
60
- file: { type: 'string' }, command: { type: 'string' }, arg: { type: 'string', multiple: true }, env: { type: 'string', multiple: true }, cwd: { type: 'string' },
71
+ file: { type: 'string' }, roles: { type: 'string' }, 'no-roles': { type: 'boolean' }, command: { type: 'string' }, arg: { type: 'string', multiple: true }, env: { type: 'string', multiple: true }, cwd: { type: 'string' },
61
72
  url: { type: 'string' }, header: { type: 'string', multiple: true }, event: { type: 'string' }, blocking: { type: 'boolean' }, timeout: { type: 'string' },
62
- 'match-agent': { type: 'string' }, 'match-label': { type: 'string' },
73
+ 'match-agent': { type: 'string' }, 'match-label': { type: 'string' }, strict: { type: 'boolean' },
63
74
  // provider
64
75
  kind: { type: 'string' },
65
- 'read-only-mode': { type: 'string' },
66
76
  models: { type: 'string' },
67
77
  };
68
78
 
@@ -115,7 +125,7 @@ async function edited(kind, name, current, values) {
115
125
  if (values.rules !== undefined) content.houseRules = await readFile(values.rules, 'utf8');
116
126
  } else if (kind === 'skills') {
117
127
  if (values.file !== undefined) content.body = await readFile(values.file, 'utf8');
118
- content.body ??= `---\nname: ${name}\ndescription: When to use this skill.\n---\n\n# ${name}\n\nSteps and checks.\n`;
128
+ content.body ??= `---\nname: ${name}\ndescription: ${JSON.stringify(values.description ?? `What ${name} does. Use when the work it is for comes up.`)}\n---\n\n# ${name}\n\n## When to use\n\n## Workflow\n\n## Verification\n`;
119
129
  } else if (kind === 'mcp') {
120
130
  if (values.command !== undefined || values.url !== undefined) content.server = {};
121
131
  const server = content.server ?? {};
@@ -151,7 +161,7 @@ async function edited(kind, name, current, values) {
151
161
  set(provider, 'label', values.label);
152
162
  set(provider, 'description', values.description);
153
163
  set(provider, 'command', values.command);
154
- set(provider, 'readOnlyMode', values['read-only-mode']);
164
+ delete provider.readOnlyMode; // Drop the retired no-op setting when saving an existing definition.
155
165
  if (values.arg?.length) provider.args = values.arg;
156
166
  if (values.env?.length) provider.env = pairs(values.env, '--env');
157
167
  const models = names(values.models);
@@ -161,11 +171,50 @@ async function edited(kind, name, current, values) {
161
171
  return content;
162
172
  }
163
173
 
174
+ /**
175
+ * alp skill check [name|DIR] [--project [DIR]] [--strict] [--json]: validates skills (Agent Skills
176
+ * format, packages/core/src/skill-validate.js). Without a name, every skill the project and the
177
+ * library hold; a name, the one that applies; a path, that directory. Existing skills are checked in
178
+ * legacy mode (format problems are warnings) unless --strict. Reads only; exit 1 on an error.
179
+ */
180
+ async function checkSkills(name, positionals, values) {
181
+ if (positionals.length > 2) throw new UsageError();
182
+ const root = path.resolve(values.project ?? process.cwd());
183
+ const mode = values.strict ? 'strict' : 'legacy';
184
+ let targets;
185
+ if (name !== undefined && (name.includes('/') || name.includes(path.sep) || name.startsWith('.'))) targets = [path.resolve(name)];
186
+ else {
187
+ const rows = await libraryEntries('skills', root, { library: alpHome() });
188
+ const chosen = name === undefined ? rows : rows.filter(row => row.name === name);
189
+ if (name !== undefined && !chosen.length) throw new Error(`No skill '${name}' in ${path.join(root, '.alp', 'skills')} or ${path.join(alpHome(), 'skills')}`);
190
+ targets = chosen.map(row => path.dirname(row.path));
191
+ }
192
+ const reports = [];
193
+ for (const target of targets) reports.push(await validateSkill(target, { mode }));
194
+ if (values.json) console.log(JSON.stringify(reports));
195
+ else {
196
+ for (const report of reports) console.log(formatValidation(report));
197
+ const failed = reports.filter(report => !report.ok).length;
198
+ const warned = reports.filter(report => report.warnings.length).length;
199
+ console.log(`${reports.length} skill${reports.length === 1 ? '' : 's'} checked (${mode}): ${failed} with errors, ${warned} with warnings.${mode === 'legacy' && warned ? ' Warnings do not stop a skill from loading; fix them when you next edit it.' : ''}`);
200
+ }
201
+ if (reports.some(report => !report.ok)) process.exitCode = 1;
202
+ }
203
+
164
204
  /** alp agent|team|skill|mcp|hook: create, change, copy, rename, remove and test library entries. */
165
205
 
166
206
  async function editCommand(kind, args) {
207
+ if (kind === 'providers' && args.some(arg => arg === '--read-only-mode' || arg.startsWith('--read-only-mode='))) throw new Error('--read-only-mode was removed; delete readOnlyMode from provider JSON and choose the session --mode read-only, workspace-write or full-access. Existing native sessions keep their mode.');
167
208
  const { values, positionals } = parseArgs({ args: projectFlag(args), allowPositionals: true, options: EDIT_OPTIONS });
168
209
  const [action, name, target] = positionals;
210
+ if (kind === 'skills' && action === 'restore') {
211
+ if (!name || positionals.length > 2 || values.project !== undefined || (values.roles !== undefined && values['no-roles'])) throw new UsageError();
212
+ const roles = values['no-roles'] ? [] : names(values.roles);
213
+ const result = await restoreSkill(name, { library: alpHome(), from: values.from, roles });
214
+ console.log(values.json ? JSON.stringify(result) : `Restored ${name} to ${result.restored} from ${result.from}; ${result.roles.length ? `given to ${result.roles.join(', ')}` : 'given to no role'}.`);
215
+ return;
216
+ }
217
+ if (kind === 'skills' && action === 'check') { await checkSkills(name, positionals, values); return; }
169
218
  if (kind === 'providers' && action !== 'add') await seedLibrary(alpHome());
170
219
  const creates = { agents: 'new', teams: 'new', skills: 'new', mcp: 'add', hooks: 'add', providers: 'add' }[kind];
171
220
  if (!name || positionals.length > (['cp', 'mv'].includes(action) ? 3 : 2) || (['cp', 'mv'].includes(action) && !target)) throw new UsageError();
@@ -208,6 +257,8 @@ async function editCommand(kind, args) {
208
257
  let revision = null;
209
258
  if (action === creates) {
210
259
  if (values.from !== undefined) current = (await getEntry(kind, values.from, { root, library: alpHome() })).content;
260
+ // A skill made from another names itself, as its directory does.
261
+ if (kind === 'skills' && current?.body !== undefined) current = { ...current, body: withSkillName(current.body, name) };
211
262
  } else {
212
263
  // Editing an entry that only a lower layer has makes this scope's copy of it.
213
264
  const entry = await getEntry(kind, name, { root, library: alpHome() }).catch(error => { if (error.code === 'NOT_FOUND') throw new Error(`No ${kind} entry '${name}'; create it with alp ${kind.replace(/s$/, '')} ${creates}`); throw error; });
@@ -215,8 +266,15 @@ async function editCommand(kind, args) {
215
266
  current = (own ?? entry).content;
216
267
  revision = own ? own.revision : null;
217
268
  }
218
- const result = await saveEntry(kind, name, await edited(kind, name, current, values), { ...options, revision });
269
+ // A new skill meets the skill format strictly; an edit of an existing one is saved as before, and told what to fix.
270
+ const result = await saveEntry(kind, name, await edited(kind, name, current, values), { ...options, revision, strict: kind === 'skills' && action === creates });
219
271
  done(result, `${action === 'edit' ? 'Saved' : 'Created'} ${name} in ${where}.`);
272
+ if (kind === 'skills' && !values.json) {
273
+ const directory = path.join(scope === 'project' ? path.join(root, '.alp') : alpHome(), 'skills', name);
274
+ const report = await validateSkill(directory);
275
+ const notes = [...(result.warnings ?? []), ...report.errors.map(finding => finding.message), ...report.warnings.map(finding => finding.message)];
276
+ for (const note of [...new Set(notes)]) console.log(`note: ${note}`);
277
+ }
220
278
  }
221
279
 
222
280
  /** alp trust: the workspaces whose hooks run without asking (ALPD §45). */
@@ -240,4 +298,45 @@ async function teamsCommand(args) {
240
298
  }
241
299
  }
242
300
 
243
- export { libraryCommand, projectFlag, pairs, names, EDIT_OPTIONS, edited, editCommand, teamsCommand };
301
+ /**
302
+ * alp packs [--project DIR] [--json]: the optional packs ALP ships, and whether the library or the
303
+ * project has them. alp pack install <id> [--project [DIR]] [--assign] [--json]: copies a pack's
304
+ * skills, agents and teams into the library (or the project's .alp/), keeping any entry already
305
+ * there; --assign (library) gives its suggested skills to roles in role-skills.json.
306
+ */
307
+ async function packsCommand(args) {
308
+ const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { project: { type: 'string' }, json: { type: 'boolean' } } });
309
+ if (positionals.length) throw new UsageError();
310
+ const root = path.resolve(values.project ?? process.cwd());
311
+ const rows = [];
312
+ for (const pack of await listPacks()) rows.push({ ...pack, installed: await packStatus(pack, { root, library: alpHome() }) });
313
+ if (values.json) { console.log(JSON.stringify(rows)); return; }
314
+ const width = Math.max(...rows.map(row => row.id.length));
315
+ for (const row of rows) {
316
+ const contents = [row.skills.length ? `skills: ${row.skills.join(', ')}` : '', row.agents.length ? `agents: ${row.agents.join(', ')}` : '', row.teams.length ? `teams: ${row.teams.join(', ')}` : ''].filter(Boolean).join('; ');
317
+ const where = [row.installed.library ? 'library' : '', row.installed.project ? 'project' : ''].filter(Boolean).join(', ');
318
+ console.log(`${row.id.padEnd(width)} ${row.description}\n${' '.repeat(width)} ${contents}${where ? ` [installed: ${where}]` : ''}`);
319
+ }
320
+ console.log('Install one with: alp pack install <id> [--project] [--assign]');
321
+ }
322
+
323
+ async function packCommand(args) {
324
+ const { values, positionals } = parseArgs({ args: projectFlag(args), allowPositionals: true, options: { project: { type: 'string' }, json: { type: 'boolean' }, assign: { type: 'boolean' } } });
325
+ const [action, id] = positionals;
326
+ if (action !== 'install' || !id || positionals.length > 2) throw new UsageError();
327
+ const scope = values.project !== undefined ? 'project' : 'library';
328
+ const root = values.project !== undefined ? path.resolve(values.project) : undefined;
329
+ if (scope === 'project') await taskProject(root);
330
+ const result = await installPack(id, { scope, root, library: alpHome(), assign: values.assign });
331
+ if (values.json) { console.log(JSON.stringify(result)); return; }
332
+ const where = scope === 'project' ? `the project ${root}` : `your library ${alpHome()}`;
333
+ for (const entry of result.installed) console.log(`installed ${entry.kind.replace(/s$/, '')} ${entry.name} ${entry.path}`);
334
+ for (const entry of result.kept) console.log(`kept ${entry.kind.replace(/s$/, '')} ${entry.name}: one already exists, and stays as it is (${entry.path})`);
335
+ for (const line of result.permissions.set) console.log(`permission ${line} (agent capped by its permission profile)`);
336
+ for (const line of result.permissions.conflicts) console.log(`warning: ${line}`);
337
+ if (result.assigned.length) console.log(`assigned ${result.assigned.join(', ')} in role-skills.json`);
338
+ else if (!values.assign && scope === 'library' && result.installed.some(entry => entry.kind === 'skills')) console.log('No role has these skills yet: rerun with --assign for the pack\'s suggestion, or alp agent edit <agent> --skills a,b.');
339
+ console.log(`Pack ${id} in ${where}. Start a new session (or close and resume) for agents to see it.`);
340
+ }
341
+
342
+ export { libraryCommand, projectFlag, pairs, names, EDIT_OPTIONS, edited, editCommand, teamsCommand, packsCommand, packCommand };
package/src/projects.js CHANGED
@@ -22,8 +22,10 @@ async function project(command, args) {
22
22
  try {
23
23
  const result = await (command === 'upgrade' ? upgradeProject : initProject)(args[0] ?? process.cwd(), { library: alpHome() });
24
24
  console.log(`ALP initialized: ${result.created.length} files created, ${result.preserved.length} existing files preserved.`);
25
- const library = await seedLibrary(alpHome());
25
+ // On upgrade an edited role-skills.json is offered the built-in role skills it never was (t-de1a).
26
+ const library = await seedLibrary(alpHome(), { offerRoleSkills: command === 'upgrade' });
26
27
  if (library.created.length || library.updated.length) console.log(`Skill library ${alpHome()}: ${library.created.length} files added, ${library.updated.length} unchanged files updated.`);
28
+ if (library.offered?.length) console.log(`New built-in skills given to roles in your edited role-skills.json: ${library.offered.join(', ')} (remove any you do not want; ALP will not add it again).`);
27
29
  if (command === 'init' && result.updated?.length) console.log(`Template model profiles refreshed: ${result.updated.join(', ')}`);
28
30
  if (command === 'upgrade') {
29
31
  console.log(`ALP upgraded: ${result.updated.length} files updated.${result.backup ? ` Backup: ${result.backup}` : ''}`);
@@ -194,7 +194,7 @@ const pause = (/** @type {number} */ ms) => Atomics.wait(new Int32Array(new Shar
194
194
 
195
195
  /**
196
196
  * Runs `action`, again after a pause while Windows reports the file busy: a virus scanner holds an
197
- * executable it just saw run (the staged bundle's --version) for a moment. About 6 s in all.
197
+ * executable it just saw run (the staged bundle's --version) for a moment. About 8 s in all.
198
198
  * @template T @param {() => T} action @param {(ms: number) => void} [sleep]
199
199
  */
200
200
  export function retryBusy(action, sleep = pause, attempts = 25) {
@@ -217,7 +217,20 @@ export function npmMessage(positionals = []) {
217
217
  /** Why this bundle cannot update itself: it was not installed by install.sh / install.ps1. @param {string} root */
218
218
  export const notInstalledMessage = root => `alp: ${root} is not an installed ALP (no app/current points at it); install the release with install.sh (Windows: install.ps1), which alp update can then keep up to date:\n curl -fsSL https://github.com/${DEFAULT_REPO}/releases/latest/download/install.sh | sh`;
219
219
 
220
- const systemTar = () => process.platform === 'win32' ? path.join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'tar.exe') : 'tar';
220
+ /**
221
+ * tar, as this platform must start it. On Windows it is the system's own bsdtar
222
+ * (%SystemRoot%\System32\tar.exe), never whatever comes first on PATH: under Git Bash that is Git's
223
+ * GNU tar, which reads a drive-letter path such as `D:\a\…\alp.zip` as a remote `host:file`
224
+ * archive and cannot read or write a zip at all. `--force-local` is not an answer: bsdtar rejects it.
225
+ *
226
+ * DUPLICATE, deliberately (t-ffe4.6): `windowsTar` in scripts/spawn-command.mjs is the same
227
+ * knowledge for the repository's own scripts. This package is published, so it cannot import from
228
+ * scripts/, and scripts/ must keep working before anything is built. Change one and change the
229
+ * other; test/integration/spawn-command.test.js asserts the two agree, and refuses any third copy.
230
+ * @param {string} platform @param {Record<string, string | undefined>} env
231
+ */
232
+ export const systemTar = (platform = process.platform, env = process.env) =>
233
+ platform === 'win32' ? path.win32.join(env.SystemRoot ?? 'C:\\Windows', 'System32', 'tar.exe') : 'tar';
221
234
 
222
235
  /** Extracts the archive into `directory` and returns the bundle inside it. @param {string} archive @param {string} directory @param {{ name: string }} asset @param {string} platform */
223
236
  function extract(archive, directory, asset, platform, run = spawnSync) {
@@ -344,8 +357,10 @@ export async function selfUpdate(args, overrides = {}) {
344
357
  if (order < 0 && !wanted) { deps.log(`alp ${deps.version} is newer than the latest release ${asset.version}; nothing to do (pass --version ${asset.version} to go back)`); return 0; }
345
358
 
346
359
  const { app, current } = bundle;
347
- // Windows cannot rename or delete a directory that a running node.exe (this one) comes from.
348
- if (deps.platform === 'win32' && asset.version === path.basename(bundle.root)) throw new Error(`ALP ${asset.version} is the version running now; Windows cannot replace it in place. Close ALP (alp daemon stop) and rerun install.ps1 to repair it`);
360
+ // A reinstall of the running version moves its directory aside instead of replacing it in place,
361
+ // on Windows too: Windows renames a directory that holds a running executable. Only a process
362
+ // whose working directory is inside the tree, or a handle opened without delete sharing, refuses
363
+ // the move (t-5294.7, board finding p-bcd9c956) — that failure is reported below, not predicted.
349
364
  // The version a running alpd uses keeps its files, like the one this process runs.
350
365
  const running = await deps.daemon().catch(() => undefined);
351
366
  try { nodeFs.accessSync(app, nodeFs.constants.W_OK); } catch { throw new Error(`${app} is not writable; run alp update with the permissions that installed ALP there`); }
@@ -379,10 +394,24 @@ export async function selfUpdate(args, overrides = {}) {
379
394
  if (reported !== asset.version) throw new Error(`The downloaded ALP reports version ${JSON.stringify(reported)}, not ${asset.version}; nothing was changed`);
380
395
  if (nodeFs.existsSync(target)) {
381
396
  // A reinstall of the running version moves it aside (its processes keep their files); any other copy is stale.
382
- if (samePath(target, bundle.root) || running?.version === asset.version) { aside = `.alp-old-${randomBytes(6).toString('hex')}`; retryBusy(() => nodeFs.renameSync(target, path.join(app, aside))); }
397
+ if (samePath(target, bundle.root) || running?.version === asset.version) {
398
+ const moved = `.alp-old-${randomBytes(6).toString('hex')}`;
399
+ try { retryBusy(() => nodeFs.renameSync(target, path.join(app, moved))); } catch (error) {
400
+ // Nothing has been replaced yet. Say what really holds the directory, so nobody looks for
401
+ // a Windows rule that does not exist (t-5294.7).
402
+ throw new Error(`Could not move ${target} aside to reinstall ALP ${asset.version}: ${error.message}. Something holds that directory: a process whose working directory is inside it, or a file handle opened without delete sharing. Stop alpd (alp daemon stop), leave that directory in any shell, and run alp update again`, { cause: error });
403
+ }
404
+ aside = moved;
405
+ }
383
406
  else nodeFs.rmSync(target, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
384
407
  }
385
- retryBusy(() => nodeFs.renameSync(unpacked, target));
408
+ try { retryBusy(() => nodeFs.renameSync(unpacked, target)); } catch (error) {
409
+ // The running version goes back where it was, so app/current still points at files (t-1f14).
410
+ if (aside && !nodeFs.existsSync(target)) {
411
+ try { nodeFs.renameSync(path.join(app, aside), target); aside = undefined; } catch { throw new Error(`${error.message}; the running ALP ${asset.version} is in ${path.join(app, aside)}: move it back to ${target}`, { cause: error }); }
412
+ }
413
+ throw error;
414
+ }
386
415
  switchCurrent(app, asset.version, { platform: deps.platform });
387
416
  } finally {
388
417
  // A cleanup failure must not hide why the update failed; a leftover staging directory goes with the next update.
package/src/usage.js CHANGED
@@ -8,6 +8,7 @@ const USAGE = `Usage:
8
8
  alp setup [directory] [--runtime codex|claude|mix] [--prefer claude|codex]
9
9
  [--claude-model M] [--codex-model M] [--claude-supervisor M] [--codex-supervisor M]
10
10
  [--claude-oracle M] [--codex-oracle M] write Phở/Cafe's agent profiles to .alp/settings.json
11
+ (keeps profiles written by hand; names other teams and the keys to edit)
11
12
  alp daemon <start|stop|restart>
12
13
  alp daemon status [--json] liveness and readiness; exit 0 ready, 3 not running, 4 not ready
13
14
  alp daemon <install|uninstall> run alpd as a login service that restarts after a crash
@@ -38,18 +39,22 @@ const USAGE = `Usage:
38
39
  alp log <session> [--json]
39
40
  alp board [--project DIR] [--json]
40
41
  alp <agents|skills|mcp|hooks> [--project DIR] [--json] the library: built-in, ~/.alp and project entries
42
+ alp skills --retired [--json] skills alp_skill_retire moved to ~/.alp/retired-skills
41
43
  alp providers [--json] ACP and Antigravity providers in your library
42
44
  alp teams [--project DIR] [--json] teams sessions run in: members, delegation, house rules
45
+ alp packs [--project DIR] [--json] optional skill packs ALP ships (backend, frontend, architecture, ...)
46
+ alp pack install <id> [--project [DIR]] [--assign] [--json] copy a pack's skills, agents and teams; existing entries are kept
43
47
  alp agent <new|edit> <name> [--project [DIR]] [--from A] [-d text] [--provider P] [--model M] [--thinking T] [--mode M]
44
48
  [--skills a,b] [--mcp a,b] [--hooks a,b] [--instructions FILE]
45
49
  alp team <new|edit> <id> [--project [DIR]] [--from ID] [--label L] [-d text] [--main A] [--member name=role]...
46
50
  [--member-model name=M]... [--member-thinking name=T]... [--delegate owner=a,b]... [--max-peers N]
47
51
  [--supervisor A] [--supervisor-model M] [--supervisor-thinking T] [--no-supervisor] [--rules FILE]
48
- alp skill new <name> [--project [DIR]] [--from S] [--file FILE]
52
+ alp skill <new|edit> <name> [--project [DIR]] [--from S] [--file FILE]
53
+ alp skill check [name|DIR] [--project [DIR]] [--strict] [--json] validate skills (format, references, links); exit 1 on errors
54
+ alp skill restore <name> [--from DIR] [--roles a,b | --no-roles] bring back a retired skill; --roles needed if it was retired without retired.json
49
55
  alp mcp add <name> [--project [DIR]] (--command C [--arg A]... [--env K=V]... [--cwd D] | --url U [--header K=V]...)
50
56
  alp hook add <name> [--project [DIR]] --event E --command C [--blocking] [--timeout SEC] [--match-agent A] [--match-label L]
51
57
  alp provider add <id> --command C [--arg A]... [--env K=V]... [--label L] [-d text] [--models a,b] an ACP agent; use id antigravity for native agy
52
- alp provider edit antigravity --read-only-mode instructions|reject legacy, no effect: agy enforces every mode itself
53
58
  alp <agent|team|skill|mcp|hook|provider> <rm|show> <name> [--project [DIR]] | <cp|mv> <from> <to> [--project [DIR]]
54
59
  alp <mcp|hook|provider> test <name> [--project [DIR]] list an MCP server's tools; run a hook once; initialize a provider
55
60
  without --project, changes go to your library in ~/.alp; built-in agents and teams are never changed