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

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.
Files changed (56) hide show
  1. package/dist/THIRD-PARTY-NOTICES.txt +1 -1
  2. package/dist/acp/main.js +1 -1
  3. package/dist/acp.js +7586 -2258
  4. package/dist/{alp-web → alp-dashboard}/THIRD-PARTY-NOTICES.txt +1 -1
  5. package/dist/{alp-web/assets/TerminalPanel-BeMws9CP.js → alp-dashboard/assets/TerminalPanel-BSjqIfNr.js} +1 -1
  6. package/dist/{alp-web/assets/index-Dl7motn1.js → alp-dashboard/assets/index-CZFfSOIE.js} +35 -35
  7. package/dist/{alp-web → alp-dashboard}/index.html +1 -1
  8. package/dist/{alp-web.js → alp-dashboard.js} +491 -323
  9. package/dist/alpd.js +11807 -5372
  10. package/dist/backup.js +1 -1
  11. package/dist/build-manifest.json +24 -6
  12. package/dist/cli.js +7 -4
  13. package/dist/daemon.d.ts +2 -2
  14. package/dist/daemon.js +8 -8
  15. package/dist/dashboard-migrate.d.ts +31 -0
  16. package/dist/dashboard-migrate.js +127 -0
  17. package/dist/dashboard-service.d.ts +69 -0
  18. package/dist/{web-service.js → dashboard-service.js} +30 -32
  19. package/dist/desktop.d.ts +56 -0
  20. package/dist/desktop.js +91 -0
  21. package/dist/interfaces.d.ts +2 -2
  22. package/dist/interfaces.js +134 -42
  23. package/dist/library.d.ts +16 -2
  24. package/dist/library.js +114 -7
  25. package/dist/paths.d.ts +6 -1
  26. package/dist/paths.js +4 -2
  27. package/dist/projects.js +2 -1
  28. package/dist/roles.d.ts +5 -5
  29. package/dist/self-update.d.ts +4 -2
  30. package/dist/self-update.js +29 -6
  31. package/dist/sessions.d.ts +0 -1
  32. package/dist/usage.d.ts +1 -1
  33. package/dist/usage.js +13 -6
  34. package/package.json +6 -6
  35. package/src/cli.js +8 -3
  36. package/src/daemon.js +10 -9
  37. package/src/dashboard-migrate.js +152 -0
  38. package/src/{web-service.js → dashboard-service.js} +54 -48
  39. package/src/desktop.js +122 -0
  40. package/src/interfaces.js +171 -58
  41. package/src/library.js +108 -9
  42. package/src/paths.js +9 -3
  43. package/src/projects.js +3 -1
  44. package/src/roles.js +4 -4
  45. package/src/self-update.js +45 -8
  46. package/src/sessions.js +0 -2
  47. package/src/usage.js +13 -6
  48. package/dist/web-service.d.ts +0 -56
  49. /package/dist/{alp-web → alp-dashboard}/alp-boundary.json +0 -0
  50. /package/dist/{alp-web → alp-dashboard}/apple-touch-icon.png +0 -0
  51. /package/dist/{alp-web → alp-dashboard}/assets/TerminalPanel-DLuoa74B.css +0 -0
  52. /package/dist/{alp-web → alp-dashboard}/assets/highlighter-BnicKQ_d.js +0 -0
  53. /package/dist/{alp-web → alp-dashboard}/assets/index-DwqDSiIi.css +0 -0
  54. /package/dist/{alp-web → alp-dashboard}/favicon-attention.svg +0 -0
  55. /package/dist/{alp-web → alp-dashboard}/favicon-running.svg +0 -0
  56. /package/dist/{alp-web → alp-dashboard}/favicon.svg +0 -0
package/src/interfaces.js CHANGED
@@ -8,13 +8,14 @@ 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
- import { alpWebEntry, alpWebScript, isWebClaimed, isWebReady, refusal, stopPreRenamePaseo, stopWebService, webOwner } from './web-service.js';
13
+ import { DASHBOARD, LEGACY_WEB, dashboardEntry, dashboardScript, isDashboardReady, isServiceClaimed, refusal, serviceOwner, stopService } from './dashboard-service.js';
14
+ import { legacyLeftovers, migrateDashboard } from './dashboard-migrate.js';
15
+ import { dashboardSettings } from '@anhlp/alp-core/user-settings';
13
16
 
14
17
  /** The Paseo integration (its web app, bridge and relay) runs as integration `paseo`. */
15
18
  const PASEO = 'paseo';
16
- /** alp-web (packages/cli/src/web), the service behind `alp web`, runs as integration `web`. */
17
- const WEB = 'web';
18
19
 
19
20
  /**
20
21
  * Starts the Paseo integration. For one release, a home that still has only the descriptor
@@ -37,7 +38,7 @@ export async function startPaseoIntegration(home) {
37
38
 
38
39
  /**
39
40
  * The entry named by the pre-rename descriptor `<home>/integrations/web.json`, and nothing else: no
40
- * environment, distribution or PATH lookup, since the name `web` now belongs to alp-web. A relative
41
+ * environment, distribution or PATH lookup, since the name `web` belonged to alp web after that. A relative
41
42
  * `main` resolves against the descriptor's directory, then the home, as discovery does.
42
43
  * @param {string} file
43
44
  * @param {string} home
@@ -62,7 +63,7 @@ async function currentProject() {
62
63
  return await stat(path.join(cwd, '.alp')).then(info => info.isDirectory(), () => false) ? cwd : undefined;
63
64
  }
64
65
 
65
- /** `--project <cwd>` when the directory `alp web` runs in is an ALP project: its grant then covers it. */
66
+ /** `--project <cwd>` when the directory `alp dashboard` runs in is an ALP project: its grant then covers it. */
66
67
  async function projectArgs() {
67
68
  const project = await currentProject();
68
69
  return project ? ['--project', project] : [];
@@ -114,7 +115,7 @@ export async function registerProject(home, directory, { timeoutMs = 5_000, conn
114
115
  }
115
116
 
116
117
  /**
117
- * Waits until the credential in `<home>/web/credentials.json` contains `project`.
118
+ * Waits until the credential in `<home>/dashboard/credentials.json` contains `project`.
118
119
  * Polls for up to `timeoutMs` (default 5,000 ms).
119
120
  * @param {string} home
120
121
  * @param {string} credentialId
@@ -122,7 +123,7 @@ export async function registerProject(home, directory, { timeoutMs = 5_000, conn
122
123
  * @param {{ timeoutMs?: number }} [options]
123
124
  */
124
125
  async function waitForGrant(home, credentialId, project, { timeoutMs = 5_000 } = {}) {
125
- const credentialsFile = path.join(home, 'web', 'credentials.json');
126
+ const credentialsFile = path.join(home, 'dashboard', 'credentials.json');
126
127
  const canonical = await realpath(project).catch(() => project);
127
128
  const deadline = Date.now() + timeoutMs;
128
129
  while (Date.now() < deadline) {
@@ -138,45 +139,76 @@ async function waitForGrant(home, credentialId, project, { timeoutMs = 5_000 } =
138
139
  return false;
139
140
  }
140
141
 
141
- /** Whether settings.json turns alp web off. @param {string} home */
142
- async function webDisabled(home) {
143
- const settings = await readFile(path.join(home, 'settings.json'), 'utf8').then(text => JSON.parse(text), () => undefined);
144
- return settings?.web?.enabled === false;
142
+ /** Whether settings.json turns alp dashboard off (`dashboard.enabled`, else `web.enabled` from before the rename). @param {string} home */
143
+ async function dashboardDisabled(home) {
144
+ const settings = await readJsonFile(path.join(home, 'settings.json'));
145
+ return dashboardSettings(settings).enabled === false;
145
146
  }
146
147
 
147
- const DISABLED = 'alp web is disabled by settings ("web.enabled": false).';
148
+ const DISABLED = 'alp dashboard is disabled by settings ("dashboard.enabled": false).';
149
+
150
+ /** A file's JSON, or undefined when it is missing or not JSON (as before: a broken file counts as none). @param {string} file */
151
+ const readJsonFile = file => readFile(file, 'utf8').then(text => { try { return JSON.parse(text); } catch { return undefined; } }, () => undefined);
152
+ /** @param {string} home */
153
+ const readPublished = home => readJsonFile(path.join(home, DASHBOARD.info));
154
+ /** @param {string} home */
155
+ const readServiceLock = home => readJsonFile(path.join(home, 'integrations', `${DASHBOARD.lock}.lock`));
156
+
157
+ /**
158
+ * The running service as its files and its listener show it, without ps (so also on Windows): the
159
+ * lock names a live pid, dashboard.json names the same pid and is alp-dashboard's, and its address
160
+ * answers. `held` is a live lock owner that is not (yet) that.
161
+ * @param {string} home
162
+ * @returns {Promise<{ pid: number, port: number, url: string } | { held: number } | undefined>}
163
+ */
164
+ async function runningDashboard(home) {
165
+ const lock = await readServiceLock(home);
166
+ if (!Number.isSafeInteger(lock?.pid) || lock.pid <= 0) return undefined;
167
+ try { process.kill(lock.pid, 0); } catch (error) { if (/** @type {any} */ (error)?.code !== 'EPERM') return undefined; }
168
+ const info = await readPublished(home);
169
+ if (info?.app === DASHBOARD.app && info.pid === lock.pid && typeof info.url === 'string' && await isDashboardReady(info.url)) return { pid: info.pid, port: info.port, url: info.url };
170
+ return { held: lock.pid };
171
+ }
172
+
173
+ /** Loopback names `--host` accepts; the service listens on 127.0.0.1 only, which serves both. */
174
+ const LOOPBACK_HOSTS = ['127.0.0.1', 'localhost'];
148
175
 
149
176
  /**
150
- * Starts alp-web unless it runs and returns the address to open, the token in its fragment (which
151
- * the browser never sends to a server). The Paseo integration from before its rename, still running
152
- * as integration `web`, is stopped first.
153
- * @param {string} home @param {string} entry
177
+ * Starts alp-dashboard unless it runs and returns the address to open, the token in its fragment
178
+ * (which the browser never sends to a server).
179
+ * @param {string} home @param {string} entry @param {{ port?: number }} [options]
154
180
  */
155
- async function serveWeb(home, entry) {
156
- await stopPreRenamePaseo(home);
157
- // A lock held by a process proven not to be alp web: say so now rather than wait for it. A
158
- // running alp-web (its web.json names the lock's pid and is answering) is left to startIntegration.
159
- const held = await webOwner(home);
160
- const published = await readFile(path.join(home, 'web.json'), 'utf8').then(text => JSON.parse(text), () => undefined);
161
- const lockPid = await readFile(path.join(home, 'integrations', 'web.lock'), 'utf8').then(text => JSON.parse(text)?.pid, () => undefined);
162
- const claimed = await isWebClaimed(published, lockPid, held);
163
- if ('reason' in held && held.alive && held.kind === 'foreign' && !claimed) throw new Error(`${refusal(home)} (${held.reason}). Stop it, then run alp web again.`);
181
+ async function serveDashboard(home, entry, { port } = {}) {
182
+ // A lock held by a process proven not to be alp dashboard: say so now rather than wait for it. A
183
+ // running alp-dashboard (its dashboard.json names the lock's pid and is answering) is left to startIntegration.
184
+ const held = await serviceOwner(home);
185
+ const published = await readPublished(home);
186
+ const lockPid = (await readServiceLock(home))?.pid;
187
+ const claimed = await isServiceClaimed(published, lockPid, held);
188
+ if ('reason' in held && held.alive && held.kind === 'foreign' && !claimed) throw new Error(`${refusal(home)} (${held.reason}). Stop it, then run alp dashboard again.`);
189
+ // `--port` asks for a port; a service already running elsewhere is not silently reused.
190
+ if (port !== undefined && claimed && published.port !== port) {
191
+ throw new Error(`alp dashboard already runs on port ${published.port} (pid ${published.pid}); you asked for port ${port}. Stop it with \`alp dashboard --stop\`, or drop --port to use the running one.`);
192
+ }
164
193
  const project = await currentProject();
165
194
  let lock;
166
- try { lock = await startIntegration({ name: WEB, entry, home, args: project ? ['--project', project] : [] }); }
195
+ try { lock = await startIntegration({ name: DASHBOARD.lock, entry, home, args: [...(project ? ['--project', project] : []), ...(port !== undefined ? ['--port', String(port)] : [])] }); }
167
196
  catch (error) {
168
197
  // Still held by a live process alp cannot prove: name it, as the wait may have been for it.
169
- const owner = await webOwner(home);
170
- if ('reason' in owner && owner.alive) throw new Error(`${error?.message ?? error}\n${refusal(home)} (${owner.reason}). If it is not alp web, stop it, then run alp web again.`, { cause: error });
198
+ const owner = await serviceOwner(home);
199
+ if ('reason' in owner && owner.alive) throw new Error(`${error?.message ?? error}\n${refusal(home)} (${owner.reason}). If it is not alp dashboard, stop it, then run alp dashboard again.`, { cause: error });
171
200
  throw error;
172
201
  }
173
- const info = await readFile(path.join(home, 'web.json'), 'utf8').then(text => JSON.parse(text), () => undefined);
174
- if (info?.app !== 'alp-web' || info.pid !== lock.pid) {
175
- const owner = await webOwner(home);
176
- throw new Error(`${refusal(home)}${'reason' in owner ? ` (${owner.reason})` : ''}. Stop pid ${lock.pid}, then run alp web again.`);
202
+ const info = await readPublished(home);
203
+ if (info?.app !== DASHBOARD.app || info.pid !== lock.pid) {
204
+ const owner = await serviceOwner(home);
205
+ throw new Error(`${refusal(home)}${'reason' in owner ? ` (${owner.reason})` : ''}. Stop pid ${lock.pid}, then run alp dashboard again.`);
206
+ }
207
+ if (typeof info.url !== 'string' || typeof info.token !== 'string' || !(await isDashboardReady(info.url))) {
208
+ throw new Error(`alp dashboard published no address; see ${path.join(home, 'logs', 'integrations', 'alp-dashboard.log')}`);
177
209
  }
178
- if (typeof info.url !== 'string' || typeof info.token !== 'string' || !(await isWebReady(info.url))) {
179
- throw new Error(`alp web published no address; see ${path.join(home, 'logs', 'integrations', 'alp-web.log')}`);
210
+ if (port !== undefined && info.port !== port) {
211
+ throw new Error(`alp dashboard is running on port ${info.port}, not ${port} (port ${port} was busy or alp dashboard was starting already); it was left running there. Stop it with \`alp dashboard --stop\` and free port ${port}, or drop --port`);
180
212
  }
181
213
  if (project) {
182
214
  await registerProject(home, project);
@@ -185,56 +217,137 @@ async function serveWeb(home, entry) {
185
217
  return `${info.url}#token=${info.token}`;
186
218
  }
187
219
 
188
- async function webCommand(args) {
220
+ /** Reports what the migration from `alp web` did, on stderr (stdout carries only the address). @param {Awaited<ReturnType<typeof migrateDashboard>>} report */
221
+ function reportMigration(report) {
222
+ if (report.stopped) console.error(`Stopped ${LEGACY_WEB.what} (pid ${report.stopped}).`);
223
+ if (report.moved.length) console.error(`Moved alp web's files to alp dashboard's names: ${report.moved.join('; ')}`);
224
+ for (const warning of report.warnings) console.error(warning);
225
+ }
226
+
227
+ /**
228
+ * alp dashboard --status, after Hermes' `hermes dashboard --status` (hermes_cli/main_dashboard.py
229
+ * _report_dashboard_status): what runs, or that nothing does; always exit 0, and nothing is changed
230
+ * (the move from `alp web` waits for a command that starts or stops). The address is printed
231
+ * without its token.
232
+ * @param {string} home
233
+ */
234
+ async function statusCommand(home) {
235
+ try {
236
+ const running = await runningDashboard(home);
237
+ if (running && 'url' in running) {
238
+ console.log('1 alp dashboard process running:');
239
+ console.log(` PID ${running.pid} [dashboard]: ${running.url} (port ${running.port})`);
240
+ } else if (running) {
241
+ const owner = await serviceOwner(home);
242
+ console.log(`No alp dashboard running. pid ${running.held} holds ${path.join(home, 'integrations', `${DASHBOARD.lock}.lock`)}${'reason' in owner ? ` (${owner.reason})` : ''}.`);
243
+ } else console.log('No alp dashboard running.');
244
+ if (await dashboardDisabled(home)) console.log(DISABLED);
245
+ const left = await legacyLeftovers(home);
246
+ if (left.legacy?.pid) console.log(`${LEGACY_WEB.what} still runs (pid ${left.legacy.pid}); \`alp dashboard\` or \`alp dashboard --stop\` stops it.`);
247
+ else if (left.legacy) console.log(`${refusal(home, LEGACY_WEB)} (${left.legacy.reason}).`);
248
+ for (const item of left.pending) console.log(`From before the rename to alp dashboard, moved by the next \`alp dashboard\`: ${item}`);
249
+ for (const item of left.kept) console.log(`Left from before the rename to alp dashboard, not used: ${item}`);
250
+ } catch (error) {
251
+ console.log(`alp dashboard could not tell everything: ${error?.message ?? error}`);
252
+ }
253
+ }
254
+
255
+ /**
256
+ * alp dashboard --stop, after Hermes' `hermes dashboard --stop` (hermes_cli/main.py
257
+ * _dashboard_lifecycle_flags): only this ALP home's service (and alp web from before the rename,
258
+ * which the move stops); nothing running is not an error; a process alp cannot prove is the service
259
+ * is left running and the command fails.
260
+ * @param {string} home
261
+ */
262
+ async function stopCommand(home) {
263
+ const report = await migrateDashboard(home);
264
+ reportMigration(report);
265
+ // alp web from before the rename still holds its lock: not stopped, so not a success.
266
+ if (report.held) process.exitCode = 1;
267
+ const owner = await serviceOwner(home);
268
+ if (!owner.alive && !('pid' in owner)) {
269
+ if (!report.stopped) console.log('No alp dashboard running for this ALP home.');
270
+ return;
271
+ }
272
+ const pid = await stopService(home);
273
+ if (pid) console.log(`Stopped alp dashboard (pid ${pid}).`);
274
+ else console.log('No alp dashboard running for this ALP home.');
275
+ }
276
+
277
+ async function dashboardCommand(args) {
278
+ // alp dashboard prints, rotates and pairs with the user's own secrets (t-1c59), and stops the
279
+ // user's service: a process an ALP agent started is refused before anything is read, stopped or printed.
280
+ if (isAgentProcess()) throw new Error('alp dashboard 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
281
  if (args[0] === 'pair') return pairCommand(args.slice(1));
190
282
  if (args[0] === 'rotate') return rotateCommand(args.slice(1));
191
- // alp-web itself in this process; its own options (--service, --rotate, --project DIR) follow.
192
- if (args[0] === 'serve') return runRole('web', alpWebScript(), args.slice(1));
193
- const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { print: { type: 'boolean' } } });
283
+ // alp-dashboard itself in this process; its own options (--service, --rotate, --project DIR, --port N) follow.
284
+ if (args[0] === 'serve') return runRole('dashboard', dashboardScript(), args.slice(1));
285
+ const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
286
+ print: { type: 'boolean' }, 'no-open': { type: 'boolean' }, status: { type: 'boolean' }, stop: { type: 'boolean' },
287
+ port: { type: 'string' }, host: { type: 'string' },
288
+ } });
194
289
  if (positionals.length) throw new UsageError();
195
- const entry = alpWebEntry();
196
290
  const home = alpHome();
197
- if (await webDisabled(home)) throw new Error(DISABLED);
291
+ // As in Hermes, the lifecycle flags win over the start flags: they report or stop, and exit.
292
+ if (values.status && values.stop) throw new UsageError();
293
+ if (values.status) return statusCommand(home);
294
+ if (values.stop) return stopCommand(home);
295
+ let port;
296
+ if (values.port !== undefined) {
297
+ port = Number(values.port);
298
+ if (!/^\d+$/.test(values.port) || port < 1024 || port > 65535) throw new Error(`--port must be a port from 1024 to 65535, not ${values.port}`);
299
+ }
300
+ // ALP's token is the dashboard's only lock and its gateway accepts only loopback Host and Origin
301
+ // names, so it is never bound beyond this machine (Hermes too refuses a non-loopback bind without
302
+ // an auth provider, which ALP does not have).
303
+ if (values.host !== undefined && !LOOPBACK_HOSTS.includes(values.host)) {
304
+ throw new Error(`alp dashboard listens on this machine only (127.0.0.1): --host ${values.host} is refused. Reach it from another machine through an SSH tunnel to 127.0.0.1.`);
305
+ }
306
+ const entry = dashboardEntry();
307
+ reportMigration(await migrateDashboard(home, { strict: true }));
308
+ if (await dashboardDisabled(home)) throw new Error(DISABLED);
198
309
  await start();
199
- const url = await serveWeb(home, entry);
310
+ let url = await serveDashboard(home, entry, { port });
311
+ if (values.host === 'localhost') url = url.replace('://127.0.0.1:', '://localhost:');
200
312
  console.log(url);
201
- if (values.print) return;
313
+ if (values.print || values['no-open']) return;
202
314
  const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'explorer' : 'xdg-open';
203
315
  spawn(opener, [url], { stdio: 'ignore', detached: true }).on('error', () => console.error('Open the address above in your browser')).unref();
204
316
  }
205
317
 
206
318
  /**
207
- * alp web rotate: alp web's token is replaced and the old one revoked, so every open page loses
208
- * access. Only the process holding the web lock writes alp web's credentials, so the service is
209
- * stopped first; `alp-web.js --rotate` then takes the lock, replaces the credential, records the
210
- * new token in web.json and releases the lock, and the service starts again with it.
319
+ * alp dashboard rotate: alp dashboard's token is replaced and the old one revoked, so every open
320
+ * page loses access. Only the process holding the dashboard lock writes its credentials, so the
321
+ * service is stopped first; `alp-dashboard.js --rotate` then takes the lock, replaces the credential,
322
+ * records the new token in dashboard.json and releases the lock, and the service starts again with it.
211
323
  */
212
324
  async function rotateCommand(args) {
213
325
  if (args.length) throw new UsageError();
214
- const entry = alpWebEntry();
326
+ const entry = dashboardEntry();
215
327
  const home = alpHome();
328
+ reportMigration(await migrateDashboard(home, { strict: true }));
216
329
  await start();
217
330
  const project = await projectArgs();
218
331
  for (let attempt = 1; ; attempt++) {
219
- await stopWebService(home);
332
+ await stopService(home);
220
333
  const rotated = await new Promise(resolve => {
221
- const rotate = entryCommand(entry, 'web', ['--rotate', ...project]);
334
+ const rotate = entryCommand(entry, 'dashboard', ['--rotate', ...project]);
222
335
  execFile(rotate.command, rotate.args, { env: { ...process.env, ALP_HOME: home }, encoding: 'utf8', timeout: 60_000, killSignal: 'SIGTERM' },
223
336
  (error, stdout, stderr) => resolve({ code: error ? (typeof error.code === 'number' ? error.code : 1) : 0, output: `${stderr}${stdout}`.trim() }));
224
337
  });
225
338
  if (rotated.code === 0) break;
226
- // Exit 3: alp web started again between the stop and the rotation; stop it once more.
227
- if (rotated.code !== 3 || attempt >= 3) throw new Error(`alp web could not rotate its token${rotated.output ? `:\n${rotated.output.slice(-2000)}` : ''}`);
339
+ // Exit 3: alp dashboard started again between the stop and the rotation; stop it once more.
340
+ if (rotated.code !== 3 || attempt >= 3) throw new Error(`alp dashboard could not rotate its token${rotated.output ? `:\n${rotated.output.slice(-2000)}` : ''}`);
228
341
  }
229
- if (await webDisabled(home)) {
230
- console.log(`alp web has a new token; the old one no longer works. ${DISABLED.replace(/\.$/, '')}, so it was not started.`);
342
+ if (await dashboardDisabled(home)) {
343
+ console.log(`alp dashboard has a new token; the old one no longer works. ${DISABLED.replace(/\.$/, '')}, so it was not started.`);
231
344
  return;
232
345
  }
233
- console.log(await serveWeb(home, entry));
346
+ console.log(await serveDashboard(home, entry));
234
347
  }
235
348
 
236
349
  /**
237
- * alp web pair: the link that pairs Paseo's app on another device with alpd through Paseo's relay
350
+ * alp dashboard pair: the link that pairs Paseo's app on another device with alpd through Paseo's relay
238
351
  * (ALPD §64). The device then signs in with the password this command prints (the token kept in
239
352
  * ~/.alp/paseo.json).
240
353
  */
@@ -256,7 +369,7 @@ export async function requestPairing(client, params, attempts = 50) {
256
369
  if (!unknown) throw outcome.error;
257
370
  await new Promise(resolve => setTimeout(resolve, 100));
258
371
  }
259
- throw last ?? new Error('alpd did not register web.pairing; run `alp web` to let the integration start, then retry');
372
+ throw last ?? new Error('alpd did not register web.pairing; run `alp dashboard pair` again to let the integration start');
260
373
  }
261
374
 
262
375
  async function pairCommand(args) {
@@ -269,7 +382,7 @@ async function pairCommand(args) {
269
382
  try {
270
383
  const pairing = await requestPairing(client, values.on ? { enable: true } : values.off ? { enable: false } : {});
271
384
  if (!pairing.relayEnabled) {
272
- console.log(`The relay is off${values.off ? ' now' : ''}. Turn it on with: alp web pair --on`);
385
+ console.log(`The relay is off${values.off ? ' now' : ''}. Turn it on with: alp dashboard pair --on`);
273
386
  return;
274
387
  }
275
388
  console.log(`Relay ${pairing.endpoint}: ${pairing.connected ? 'connected' : 'connecting'}`);
@@ -291,4 +404,4 @@ async function acpCommand(args) {
291
404
  await runAcp({ daemonEntry: DAEMON_ENTRY });
292
405
  }
293
406
 
294
- export { webCommand, pairCommand, acpCommand };
407
+ export { dashboardCommand, pairCommand, acpCommand };
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/paths.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { existsSync } from 'node:fs';
2
2
  import { fileURLToPath, pathToFileURL } from 'node:url';
3
3
  import path from 'node:path';
4
- import { selfEntry } from '@anhlp/alp-core/packaged';
4
+ import { daemonEntry, selfEntry } from '@anhlp/alp-core/packaged';
5
5
 
6
6
  /** Locate artifacts in either the independently shipped CLI or the legacy root build. */
7
7
  export function distributionEntry(name) {
@@ -14,5 +14,11 @@ export function distributionEntry(name) {
14
14
  return candidates.find(candidate => existsSync(candidate)) ?? candidates[0];
15
15
  }
16
16
 
17
- /** What starts alpd: alpd.js under Node (named through app/current in the ALP bundle). */
18
- export const DAEMON_ENTRY = selfEntry(fileURLToPath(distributionEntry('alpd.js')));
17
+ /** alpd.js, which `alp daemon run` runs in this process (named through app/current in the ALP bundle). */
18
+ export const DAEMON_SCRIPT = selfEntry(fileURLToPath(distributionEntry('alpd.js')));
19
+
20
+ /**
21
+ * What starts alpd: the bundle's native alpd when it ships one (t-81b0.9), else alpd.js under Node;
22
+ * ALP_NATIVE_DAEMON=0 keeps the Node alpd. Named through app/current in the ALP bundle.
23
+ */
24
+ export const DAEMON_ENTRY = daemonEntry(fileURLToPath(distributionEntry('alpd.js')));
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}` : ''}`);
package/src/roles.js CHANGED
@@ -3,14 +3,14 @@ import { runBridge } from '@anhlp/alp-core/bridges';
3
3
  import { UsageError } from './usage.js';
4
4
 
5
5
  /**
6
- * The role subcommands (t-1e02): `alp daemon run`, `alp web serve` and `alp bridge acp|antigravity`
7
- * run alpd, alp-web and the MCP bridges in this process: they import the same scripts that
8
- * `node alpd.js` and `node alp-web.js` run. Services and MCP entries written by the single-file
6
+ * The role subcommands (t-1e02): `alp daemon run`, `alp dashboard serve` and `alp bridge acp|antigravity`
7
+ * run alpd, alp-dashboard and the MCP bridges in this process: they import the same scripts that
8
+ * `node alpd.js` and `node alp-dashboard.js` run. Services and MCP entries written by the single-file
9
9
  * executable of 0.0.1-beta.5/6 still name them.
10
10
  *
11
11
  * The role's module reads its options from process.argv as when run directly, so argv is rewritten
12
12
  * to `[runtime, entry, ...args]` before the module loads.
13
- * @param {'daemon' | 'web' | 'acp'} role
13
+ * @param {'daemon' | 'dashboard' | 'acp'} role
14
14
  * @param {string} file the role's script beside this CLI
15
15
  * @param {string[]} args
16
16
  */