@astryxdesign/cli 0.7.2 → 0.7.3-canary.02f5fe4

package/foundation/release/cache.test.mjs

@@ -802,8 +802,28 @@ describe('stopped and damaged installs heal', () => {
   });
 });
 
+/** @param {number} pid */
+const alive = pid => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** @param {() => boolean} done @param {number} ms */
+const waitFor = async (done, ms) => {
+  const end = Date.now() + ms;
+  while (Date.now() < end) {
+    if (done()) return true;
+    await new Promise(r => setTimeout(r, 100));
+  }
+  return done();
+};
+
 describe('runNpm time limit', () => {
-  it('ends a package manager that ignores SIGTERM, leaving no process behind', () => {
+  it('ends a package manager that ignores SIGTERM, leaving no process behind', async () => {
     const marker = tempDir('npm-pid');
     const pidFile = path.join(marker, 'pid');
     const result = runNpm([], {
@@ -819,30 +839,13 @@ describe('runNpm time limit', () => {
     });
     expect(/** @type {any} */ (result.error)?.code).toBe('ETIMEDOUT');
     const pid = Number(fs.readFileSync(pidFile, 'utf-8'));
-    expect(() => process.kill(pid, 0)).toThrow();
+    // The guard sends SIGKILL and exits at once; the killed process can still
+    // exist for a moment (the signal in flight, or awaiting reaping).
+    expect(await waitFor(() => !alive(pid), 5_000)).toBe(true);
   });
 });
 
 describe('no install outlives its run', () => {
-  /** @param {number} pid */
-  const alive = pid => {
-    try {
-      process.kill(pid, 0);
-      return true;
-    } catch {
-      return false;
-    }
-  };
-  /** @param {() => boolean} done @param {number} ms */
-  const waitFor = async (done, ms) => {
-    const end = Date.now() + ms;
-    while (Date.now() < end) {
-      if (done()) return true;
-      await new Promise(r => setTimeout(r, 100));
-    }
-    return done();
-  };
-
   it('ends npm when the run that started it is killed outright, and removes its process-id record', async () => {
     const dir = tempDir('orphan');
     const pidFile = path.join(dir, 'npm-pid');

package/foundation/release/global-state.d.mts

@@ -20,9 +20,11 @@
  */
 /**
  * Why an update notice did not print: `already-shown` (it printed within the
- * day) or `no-newer` (nothing newer is known). Recorded only while the run
+ * day), `no-newer` (nothing newer is known), or `no-project` (the folder
+ * installs Core but belongs to no Astryx project, so no install command
+ * fits). Recorded only while the run
  * holds the state file's lock.
- * @typedef {{reason: 'already-shown' | 'no-newer', at: number}} NoticeSkip
+ * @typedef {{reason: 'already-shown' | 'no-newer' | 'no-project', at: number}} NoticeSkip
  */
 /**
  * The state file.
@@ -242,11 +244,13 @@ export type GlobalState = {
 };
 /**
  * Why an update notice did not print: `already-shown` (it printed within the
- * day) or `no-newer` (nothing newer is known). Recorded only while the run
+ * day), `no-newer` (nothing newer is known), or `no-project` (the folder
+ * installs Core but belongs to no Astryx project, so no install command
+ * fits). Recorded only while the run
  * holds the state file's lock.
  */
 export type NoticeSkip = {
-    reason: "already-shown" | "no-newer";
+    reason: "already-shown" | "no-newer" | "no-project";
     at: number;
 };
 /**

package/foundation/release/global-state.mjs

@@ -68,9 +68,11 @@ export const CHECK_INTERVAL_MS = 24 * 60 * 60_000;
 
 /**
  * Why an update notice did not print: `already-shown` (it printed within the
- * day) or `no-newer` (nothing newer is known). Recorded only while the run
+ * day), `no-newer` (nothing newer is known), or `no-project` (the folder
+ * installs Core but belongs to no Astryx project, so no install command
+ * fits). Recorded only while the run
  * holds the state file's lock.
- * @typedef {{reason: 'already-shown' | 'no-newer', at: number}} NoticeSkip
+ * @typedef {{reason: 'already-shown' | 'no-newer' | 'no-project', at: number}} NoticeSkip
  */
 
 /**

package/foundation/release/handoff.d.mts

@@ -10,6 +10,14 @@
  * @returns {string}
  */
 export function whoAnsweredLine(choice: import("./choose.mjs").ReleaseChoice, computer?: boolean): string;
+/**
+ * The line for a run this copy answers in place of the project's own CLI,
+ * which a host declined, when this copy is that CLI's release (FR2).
+ * @param {string} version
+ * @param {string} reason the reason, as {@link declinedReasonText} words it
+ * @returns {string}
+ */
+export function inPlaceOfProjectLine(version: string, reason: string): string;
 /**
  * The line for a run handed to the project's own CLI.
  * @param {string} projectVersion
@@ -41,15 +49,26 @@ export function progressText(event: "install" | "wait", version: string): string
  * @returns {string}
  */
 export function fallbackLine(wanted: string, reason: string, answering: string): string;
+/**
+ * The fallback warning's reason for a project CLI a host declined.
+ * @param {string} reason the host's own words
+ * @returns {string}
+ */
+export function declinedReasonText(reason: string): string;
 /**
  * Choose who answers and hand off when it is not this copy.
- * @param {{cliRoot: string, argv: string[]}} input argv after `node astryx`
- * @returns {Promise<void>} resolves when this copy answers
+ * @param {{cliRoot: string, argv: string[], declinedProjectCli?: string}} input
+ *   argv after `node astryx`; the reason a programmatic host declined the
+ *   project's own CLI, when it did
+ * @returns {Promise<import('../../host/index.js').HostedCliResult | undefined>}
+ *   resolves with nothing when this copy answers, and with that release's
+ *   result when another package set's host entry answered a hosted run
  */
-export function startRun({ cliRoot, argv }: {
+export function startRun({ cliRoot, argv, declinedProjectCli }: {
     cliRoot: string;
     argv: string[];
-}): Promise<void>;
+    declinedProjectCli?: string;
+}): Promise<import("../../host/index.js").HostedCliResult | undefined>;
 /**
  * How long a hand-off waits after an interrupt before passing it on to a CLI
  * that is still running. An interrupt sent to the whole process group (a

package/foundation/release/handoff.mjs

@@ -19,9 +19,26 @@
  * (notices.mjs); a global copy also starts the daily update check, which
  * installs nothing (global-state.mjs).
  *
- * @input  the running copy, argv, the working folder
- * @output returns when this copy answers; otherwise never returns
- * @position foundation/release — called once by clients/cli/bin/astryx.mjs.
+ * A programmatic host that found the project's own CLI and did not run it
+ * passes the reason (spec AST-081 FR1, FR2). That run is never handed to the
+ * project's CLI: this copy answers in its place when it is that CLI's release,
+ * saying so in a line of its own; a package set of the host's whose CLI is
+ * that release answers through its own host entry; and otherwise this copy
+ * answers as for a release that cannot be obtained, with the warning naming
+ * the reason.
+ *
+ * A hosted run installs nothing (architecture:cli-surface INV30): a release
+ * other than this copy comes only from the first of the host's package sets
+ * that qualifies. When that CLI ships a host entry, the entry runs in this
+ * process with the same inputs, discover sources included, and the host's
+ * call settles with its result; otherwise its bin takes the run. With no such
+ * set, this copy answers, announced.
+ *
+ * @input  the running copy, argv, the working folder, and a host's
+ *   declined-project-CLI reason
+ * @output returns when this copy answers, or with another release's result
+ *   when its host entry answered; never returns after a hand-off to a bin
+ * @position foundation/release — called once per run by clients/cli/run.mjs.
  */
 
 import {spawn} from 'node:child_process';
@@ -32,8 +49,10 @@ import {
   isGlobalCopy,
   namesWhoAnswered,
   packageRootOf,
+  projectRootOf,
   runningCopy,
 } from './choose.mjs';
+import {readReleaseFacts} from './project.mjs';
 import {ensureRelease, userCacheDir} from './cache.mjs';
 import {
   maybeFetchCore,
@@ -43,6 +62,8 @@ import {
 import {recordRunChoice} from './run-context.mjs';
 import {noticeLines} from './notices.mjs';
 import {cliDoor, runWithCliDoor} from '../env/cli-command.mjs';
+import {hostedRun} from '../runtime/package-root.mjs';
+import {qualifyingRoot} from '../runtime/package-set.mjs';
 
 /** Where each release's notes are published. */
 
@@ -63,6 +84,17 @@ export function whoAnsweredLine(choice, computer = false) {
     : `astryx: answered by CLI ${choice.version} with Core ${core}, outside a project`;
 }
 
+/**
+ * The line for a run this copy answers in place of the project's own CLI,
+ * which a host declined, when this copy is that CLI's release (FR2).
+ * @param {string} version
+ * @param {string} reason the reason, as {@link declinedReasonText} words it
+ * @returns {string}
+ */
+export function inPlaceOfProjectLine(version, reason) {
+  return `astryx: answered by CLI ${version}, the release of this project's CLI, in its place (${reason})`;
+}
+
 /**
  * The line for a run handed to the project's own CLI.
  * @param {string} projectVersion
@@ -131,16 +163,32 @@ function failUnavailable(message, json) {
   process.exit(1);
 }
 
+/**
+ * The fallback warning's reason for a project CLI a host declined.
+ * @param {string} reason the host's own words
+ * @returns {string}
+ */
+export function declinedReasonText(reason) {
+  return `project CLI skipped: ${reason}`;
+}
+
 /**
  * Choose who answers and hand off when it is not this copy.
- * @param {{cliRoot: string, argv: string[]}} input argv after `node astryx`
- * @returns {Promise<void>} resolves when this copy answers
+ * @param {{cliRoot: string, argv: string[], declinedProjectCli?: string}} input
+ *   argv after `node astryx`; the reason a programmatic host declined the
+ *   project's own CLI, when it did
+ * @returns {Promise<import('../../host/index.js').HostedCliResult | undefined>}
+ *   resolves with nothing when this copy answers, and with that release's
+ *   result when another package set's host entry answered a hosted run
  */
-export async function startRun({cliRoot, argv}) {
+export async function startRun({cliRoot, argv, declinedProjectCli}) {
   const json = argv.includes('--json');
   const self = runningCopy(cliRoot);
   const cacheDir = userCacheDir();
-  const global = isGlobalCopy(cliRoot, cacheDir);
+  // A host carries its own CLI and keeps it current itself: a hosted copy
+  // runs none of the global copy's background work, and installs nothing.
+  const hosted = hostedRun();
+  const global = !hosted && isGlobalCopy(cliRoot, cacheDir);
   if (global) {
     try {
       maybeStartCheck();
@@ -189,7 +237,46 @@ export async function startRun({cliRoot, argv}) {
     };
   }
 
-  if (choice.unavailable && choice.copy === 'project') {
+  // A host declined the project's own CLI (FR2): the run is never handed to
+  // it. The release equal to that CLI's version answers in its place when
+  // this copy is that release, or when a package set of the host's holds it
+  // with a host entry; otherwise this copy answers, announced as for a release
+  // that cannot be obtained, naming the reason.
+  let declined = null;
+  /** Set when this copy answers in place of the declined CLI, its release. */
+  let inPlace = null;
+  if (
+    declinedProjectCli &&
+    choice.copy === 'project' &&
+    choice.answer !== 'self'
+  ) {
+    if (choice.version === self.version) {
+      // Still the project CLI's release (`copy` stays `project`), never the
+      // release matched to the project's Core, which can be another.
+      choice = {...choice, answer: 'self', bin: null, unavailable: null};
+      inPlace = declinedReasonText(declinedProjectCli);
+    } else {
+      const served = hosted
+        ? qualifyingRoot({
+            release: choice.version,
+            projectDir: projectDirOf(process.cwd()),
+            roots: hosted.roots,
+            needsHostEntry: true,
+          })
+        : null;
+      if (served && 'root' in served && served.hostEntry) {
+        const answered = await answerInPackageSet(
+          served.hostEntry,
+          served.root,
+          {argv, declinedProjectCli},
+        );
+        if (answered) return answered;
+      }
+      declined = declinedReasonText(declinedProjectCli);
+    }
+  }
+
+  if (!declined && choice.unavailable && choice.copy === 'project') {
     failUnavailable(
       `This project's CLI ${choice.version} could not be started: ${choice.unavailable}. Reinstall the project's dependencies.`,
       json,
@@ -245,6 +332,11 @@ export async function startRun({cliRoot, argv}) {
     });
   };
 
+  if (declined) {
+    await fallBack(declined);
+    return;
+  }
+
   if (choice.unavailable) {
     await fallBack(choice.unavailable);
     return;
@@ -256,6 +348,8 @@ export async function startRun({cliRoot, argv}) {
     // line; a hint after the command, once a day, says how to match it.
     if (!json && (choice.copy === 'matched' || choice.copy === 'carried'))
       console.error(whoAnsweredLine(choice, computer));
+    else if (!json && inPlace)
+      console.error(inPlaceOfProjectLine(choice.version, inPlace));
     process.once('exit', code => {
       if (code === 0) notify();
     });
@@ -263,6 +357,32 @@ export async function startRun({cliRoot, argv}) {
   }
 
   let bin = choice.bin;
+  if (!bin && hosted) {
+    const served = qualifyingRoot({
+      release: choice.version,
+      projectDir: projectDirOf(process.cwd()),
+      roots: hosted.roots,
+    });
+    if (!('root' in served)) {
+      await fallBack(served.reason);
+      return;
+    }
+    if (served.hostEntry) {
+      const answered = await answerInPackageSet(served.hostEntry, served.root, {
+        argv,
+      });
+      if (answered) return answered;
+    }
+    // A hosted run installs nothing (INV30): a set whose CLI starts through
+    // neither its host entry nor a bin leaves this copy to answer.
+    if (!served.bin) {
+      await fallBack(
+        `the CLI ${choice.version} in the package set at ${served.root} could not be started`,
+      );
+      return;
+    }
+    bin = served.bin;
+  }
   if (!bin) {
     const release = ensureRelease(choice.version, {
       cacheDir,
@@ -295,6 +415,53 @@ export async function startRun({cliRoot, argv}) {
  */
 export const INTERRUPT_GRACE_MS = 5000;
 
+/**
+ * The project folder a run in `cwd` belongs to, or null outside a project.
+ * @param {string} cwd
+ * @returns {string | null}
+ */
+function projectDirOf(cwd) {
+  try {
+    return projectRootOf(readReleaseFacts(cwd));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Hand a hosted run over to the CLI of one of the host's package sets,
+ * through that CLI's own host entry, in this process, with the inputs this run
+ * got: the arguments, the folder, the command name, the approved integrations,
+ * the discover sources, and the reason the host declined the project's CLI.
+ * Its roots are that package set alone. That CLI prints its own who-answered
+ * line and notices, and the host's call settles with its result.
+ * @param {string} hostEntry the package set's `host/index.mjs`
+ * @param {string} root the package set
+ * @param {{argv: string[], declinedProjectCli?: string}} run
+ * @returns {Promise<import('../../host/index.js').HostedCliResult | null>} null
+ *   when the entry cannot be loaded, before anything ran
+ */
+async function answerInPackageSet(hostEntry, root, {argv, declinedProjectCli}) {
+  const hosted = hostedRun();
+  if (!hosted?.loadHostEntry) return null;
+  let answer;
+  try {
+    answer = await hosted.loadHostEntry(hostEntry);
+  } catch {
+    return null;
+  }
+  const door = cliDoor();
+  return answer({
+    argv,
+    cwd: process.cwd(),
+    roots: [root],
+    integrations: [...hosted.integrations],
+    discoverSources: [...hosted.discoverSources],
+    ...(door ? {cliCommand: door} : {}),
+    ...(declinedProjectCli ? {declinedProjectCli} : {}),
+  });
+}
+
 /**
  * Run `bin` as this run and end with its exit status.
  * @param {string} bin

package/foundation/release/notices.d.mts

@@ -91,24 +91,71 @@ export function globalBehind({ self, stateDir }: {
     };
     stateDir?: string;
 }): GlobalBehind | null;
+/**
+ * The command that adds a package to the project of a run in `cwd`, with the
+ * project's package manager (spec AST-081 FR12). Null when `cwd` belongs to
+ * no project `spec:AST-040` FR9 defines, and in a folder inside the project
+ * whose package.json is not the project's (see {@link installFolder}): a run
+ * there loads integrations from that package.json, so a package added to the
+ * project would stay unused there, and the advice is
+ * {@link RUN_FROM_PROJECT}.
+ * @param {string} cwd
+ * @returns {((name: string) => string) | null}
+ */
+export function projectAddCommand(cwd: string): ((name: string) => string) | null;
 /**
  * The commands that bring a project's own CLI and Core to one release, with
  * the project's package manager: when the CLI is newer, Core up to it and then
  * the codemods from Core's release; otherwise the CLI to Core's release.
+ * Null in a folder that belongs to no project, or whose package.json is not
+ * the project's (see {@link installFolder}).
  * @param {{cwd: string, cli: string, core: string}} options
- * @returns {string}
+ * @returns {string | null}
  */
 export function alignCliAndCore({ cwd, cli, core }: {
     cwd: string;
     cli: string;
     core: string;
-}): string;
+}): string | null;
+/**
+ * Where a command that adds an Astryx package runs, for a run in `cwd`: in
+ * the project `spec:AST-040` FR9 defines, which stops at a repository root
+ * and never counts the home folder (spec AST-081 FR2, FR10). Null when `cwd`
+ * belongs to no such project, so no command adds anything. When `cwd`'s
+ * nearest package.json is not the project's, as in a tool folder that
+ * installs its own Core, a package manager would add to the tool's
+ * package.json, so `moved` says the command runs in the project's folder.
+ * @param {string} cwd
+ * @returns {{dir: string, moved: boolean} | null}
+ */
+export function installFolder(cwd: string): {
+    dir: string;
+    moved: boolean;
+} | null;
+/**
+ * The command that adds the CLI at Core's version, for a run in `cwd` whose
+ * Core is `core`, with the project's package manager in the project root.
+ * `command` is null in a folder inside the project whose package.json is not
+ * the project's (see {@link installFolder}), where the advice is
+ * {@link RUN_FROM_PROJECT}. Null when the folder belongs to no project.
+ * @param {{cwd: string, core: string}} options
+ * @returns {{root: string, core: string, command: string | null} | null}
+ */
+export function cliInstallAdvice({ cwd, core }: {
+    cwd: string;
+    core: string;
+}): {
+    root: string;
+    core: string;
+    command: string | null;
+} | null;
 /**
  * The hint for a project with no CLI of its own, answered by `answered` while
  * its Core is `core`: the command that adds the CLI at Core's version, with
- * the project's package manager.
+ * the project's package manager (see {@link cliInstallAdvice}). Null when no
+ * command fits, or when the project the command adds to already matches.
  * @param {{cwd: string, answered: string, core: string}} options
- * @returns {{root: string, line: string}}
+ * @returns {{root: string, line: string} | null}
  */
 export function noCliHint({ cwd, answered, core }: {
     cwd: string;
@@ -117,15 +164,16 @@ export function noCliHint({ cwd, answered, core }: {
 }): {
     root: string;
     line: string;
-};
+} | null;
 /**
  * The hint's text.
  * @param {string} answered
  * @param {string} core
- * @param {string} command the command that adds the CLI at Core's version
+ * @param {string | null} command the command that adds the CLI at Core's
+ *   version; null in a folder whose package.json is not the project's
  * @returns {string}
  */
-export function noCliHintLine(answered: string, core: string, command: string): string;
+export function noCliHintLine(answered: string, core: string, command: string | null): string;
 /**
  * The command that installs the CLI at `version` in the project at `root`,
  * with its package manager.
@@ -140,7 +188,7 @@ export function addCliCommand(root: string, version: string): string;
  * @param {{cwd: string, current: string, stateDir?: string}} options
  * @returns {ProjectLag | null}
  */
-export function projectLag({ cwd, current, stateDir }: {
+export function projectLag({ cwd, current: given, stateDir }: {
     cwd: string;
     current: string;
     stateDir?: string;
@@ -207,6 +255,12 @@ export function noticeLines({ cwd, self, choice, json, stateDir, cacheDir, now,
 }): string[];
 /** A notice prints at most once in this long. */
 export const NOTICE_INTERVAL_MS: number;
+/**
+ * What to tell a run in a folder inside a project whose package.json is not
+ * the project's: run from the project's folder, since adding there would make
+ * the folder a project of its own (spec AST-081 FR2).
+ */
+export const RUN_FROM_PROJECT: "Run this from the Astryx project's folder, or declare an Astryx package in this folder's package.json to make it a project of its own.";
 export type GlobalBehind = {
     /**
      * the global copy's version