@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/foundation/agent-docs/agent-doc-state.mjs

@@ -97,15 +97,75 @@ export function isAstryxInitialized(targetDir = process.cwd()) {
 }
 
 /**
- * The one-line next-step both postinstall nudges print. Kept here so layer 1
- * (core) and layer 2 (cli) can never word it differently.
+ * Does an agent working in `startDir` already have the Astryx prompt in reach?
  *
- * Scoped package form (`@astryxdesign/cli`) — always resolves to us, even before
- * the CLI is installed. Bare `npx astryx` would fetch an unrelated look-alike
+ * Coding agents read the agent docs between the repository root and the folder
+ * they work in. So inside a git repository, init's block in any folder from
+ * `startDir` up to the repository root counts: a workspace package of a
+ * monorepo initialized at its root is set up. Outside a repository only
+ * `startDir` itself is checked, as {@link isAstryxInitialized} does. Both the
+ * per-command nudge and the postinstall nudges ask this.
+ *
+ * @param {string} [startDir=process.cwd()]
+ * @returns {boolean}
+ */
+export function isAstryxPromptInReach(startDir = process.cwd()) {
+  const start = path.resolve(startDir);
+  const repositoryRoot = findRepositoryRoot(start);
+  if (!repositoryRoot) return isAstryxInitialized(start);
+  for (let dir = start; ; dir = path.dirname(dir)) {
+    if (isAstryxInitialized(dir)) return true;
+    if (dir === repositoryRoot) return false;
+  }
+}
+
+/**
+ * The nearest folder at or above `start` that holds `.git` (a folder, or the
+ * file a worktree uses), or null outside a repository.
+ * @param {string} start
+ * @returns {string | null}
+ */
+function findRepositoryRoot(start) {
+  for (let dir = start; ; ) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * The invocation the setup nudge falls back to when the CLI's picker
+ * (`getCliInvocation`) cannot be loaded. Scoped package form
+ * (`@astryxdesign/cli`) — always resolves to us, even before the CLI is
+ * installed. npx with the unscoped name would fetch an unrelated look-alike
  * package (see PR #4151).
  */
-export const SETUP_NUDGE =
-  '\nNext step: run `npx @astryxdesign/cli init` to finish setup and install the Astryx agent prompt.\n\n';
+export const SETUP_INVOCATION = 'npx @astryxdesign/cli';
+
+/**
+ * The one-line next-step every setup layer prints. Kept here so layer 1
+ * (core), layer 2 (cli postinstall) and layer 3 (each command) can never word
+ * it differently. Each layer passes the stem from the CLI's picker when it can
+ * load it.
+ *
+ * @param {string} [invocation] the CLI invocation stem, e.g. `pnpm exec astryx`
+ * @param {{before?: string | null}} [options] `before`: a command to run
+ *   first, such as the one that adds the CLI to a project that has none
+ * @returns {string}
+ */
+export function setupNudge(
+  invocation = SETUP_INVOCATION,
+  {before = null} = {},
+) {
+  const run = before
+    ? `\`${before}\`, then \`${invocation} init\``
+    : `\`${invocation} init\``;
+  return `\nNext step: run ${run} to finish setup and install the Astryx agent prompt.\n\n`;
+}
+
+/** The nudge with the fallback invocation. */
+export const SETUP_NUDGE = setupNudge();
 
 /**
  * Pure decision: should a postinstall print the setup nudge? Shared by BOTH

package/foundation/agent-docs/agent-docs.d.mts

@@ -97,11 +97,11 @@ export function detectStylingSystem(targetDir: string): "stylex" | "tailwind" |
  * among them. An agent cannot ask for a topic it was never told about, and
  * `getting-started` is the one it should reach for first.
  *
- * @param {string} version
+ * @param {string | null} version the Core version
  * @param {{coreDir?: string|null, invocation?: string, stylingSystem?: 'stylex'|'tailwind'|'css', zh?: boolean, lang?: string, topics?: string[], agentDocs?: Array<{package: string, append: readonly string[]}>}} [options]
  * @returns {string}
  */
-export function generateCompressedIndex(version: string, { coreDir, invocation, stylingSystem, topics, agentDocs, }?: {
+export function generateCompressedIndex(version: string | null, { coreDir, invocation, stylingSystem, topics, agentDocs, }?: {
     coreDir?: string | null;
     invocation?: string;
     stylingSystem?: "stylex" | "tailwind" | "css";
@@ -226,4 +226,5 @@ export function installAgentDocs(targetDir: string, { zh, lang, agent, paths, on
 }): string[];
 import { discoverAgentDocs } from './agent-doc-state.mjs';
 import { isAstryxInitialized } from './agent-doc-state.mjs';
-export { discoverAgentDocs, isAstryxInitialized };
+import { isAstryxPromptInReach } from './agent-doc-state.mjs';
+export { discoverAgentDocs, isAstryxInitialized, isAstryxPromptInReach };

package/foundation/agent-docs/agent-docs.mjs

@@ -42,15 +42,17 @@ import {
   LEGACY_MARKER_END,
   discoverAgentDocs,
   isAstryxInitialized,
+  isAstryxPromptInReach,
 } from './agent-doc-state.mjs';
 
 // The agent-doc locations, markers, and the setup-state predicates
-// (discoverAgentDocs, isAstryxInitialized) are the ONE canonical contract. They
-// live in the dependency-free leaf ./agent-doc-state.mjs so the postinstall
-// nudge (enforcement layer 2) can load them safely at install time. Re-exported
-// here so existing importers (init/upgrade commands, the layer-3 nudge in
-// clients/cli/index.mjs, tests) keep their `from './agent-docs.mjs'` paths.
-export {discoverAgentDocs, isAstryxInitialized};
+// (discoverAgentDocs, isAstryxInitialized, isAstryxPromptInReach) are the ONE
+// canonical contract. They live in the dependency-free leaf
+// ./agent-doc-state.mjs so the postinstall nudge (enforcement layer 2) can load
+// them safely at install time. Re-exported here so existing importers
+// (init/upgrade commands, the layer-3 nudge in clients/cli/index.mjs, tests)
+// keep their `from './agent-docs.mjs'` paths.
+export {discoverAgentDocs, isAstryxInitialized, isAstryxPromptInReach};
 
 const MAX_PROJECT_AGENT_DOC_LINES = 32;
 const MANAGED_MARKER_TEXT = /(?:ASTRYX|XDS):(START|END)/u;
@@ -377,7 +379,7 @@ export function detectStylingSystem(targetDir) {
  * among them. An agent cannot ask for a topic it was never told about, and
  * `getting-started` is the one it should reach for first.
  *
- * @param {string} version
+ * @param {string | null} version the Core version
  * @param {{coreDir?: string|null, invocation?: string, stylingSystem?: 'stylex'|'tailwind'|'css', zh?: boolean, lang?: string, topics?: string[], agentDocs?: Array<{package: string, append: readonly string[]}>}} [options]
  * @returns {string}
  */
@@ -418,9 +420,9 @@ export function generateCompressedIndex(
       // Best-effort: component count is cosmetic; fall back to the default.
     }
   }
-
-  // Header — state the CLI prefix once; commands below are shown as `astryx <cmd>`.
   lines.push(`Astryx v${version} · ${componentCount} components`);
+
+  // State the CLI prefix once; commands below are shown as `astryx <cmd>`.
   lines.push(
     `CLI: run every command as \`${run} <cmd>\` (shown below as \`astryx ...\`).`,
   );

package/foundation/agent-docs/computer-agent-text.d.mts

@@ -0,0 +1,133 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * A home-folder path as a person reads it: `~/.claude/skills/astryx`.
+ * @param {string} file
+ * @param {string} [home]
+ * @returns {string}
+ */
+export function displayHomePath(file: string, home?: string): string;
+/**
+ * The skill file's absolute path.
+ * @param {string} [home]
+ * @returns {string}
+ */
+export function computerSkillFile(home?: string): string;
+/**
+ * The absolute path of each link the table names, and whether it is wanted
+ * on this computer (its condition folder exists).
+ * @param {string} [home]
+ * @returns {Array<{path: string, wanted: boolean, mode: 'link' | 'copy'}>}
+ */
+export function computerSkillLinks(home?: string): Array<{
+    path: string;
+    wanted: boolean;
+    mode: "link" | "copy";
+}>;
+/**
+ * The command the computer-level text tells agents to run: the host's door
+ * when one started this run, else `astryx`. An integration's `cliCommand`
+ * never applies: no project, so no integration, is in scope.
+ * @returns {string}
+ */
+export function computerAgentCommand(): string;
+/**
+ * The full skill file.
+ * @param {{command?: string}} [options]
+ * @returns {string}
+ */
+export function renderComputerAgentText({ command, }?: {
+    command?: string;
+}): string;
+/**
+ * Read-only: the state of the skill file against this release's rendering,
+ * then of each place the table wants on this computer, or that Astryx linked.
+ * @param {{home?: string, command?: string, links?: readonly string[]}} [options]
+ *   `links`: the links Astryx made, from the settings file
+ * @returns {Array<{path: string, state: ComputerAgentTextState, link?: true}>}
+ */
+export function inspectComputerAgentText({ home, command, links, }?: {
+    home?: string;
+    command?: string;
+    links?: readonly string[];
+}): Array<{
+    path: string;
+    state: ComputerAgentTextState;
+    link?: true;
+}>;
+/**
+ * Write or refresh the skill file, and link it into every folder the table
+ * wants on this computer. A file without the Astryx markers, an edited one, a
+ * symlinked one, and a link target holding anything Astryx did not create are
+ * kept as they are. Returns the receipt rows and the links that now point at
+ * the skill folder, for the settings file.
+ * @param {{home?: string, command?: string}} [options]
+ * @returns {{rows: import('../../api/init/init.type.mjs').InitUserFile[], links: string[]}}
+ */
+export function writeComputerAgentText({ home, command }?: {
+    home?: string;
+    command?: string;
+}): {
+    rows: import("../../api/init/init.type.mjs").InitUserFile[];
+    links: string[];
+};
+/**
+ * Remove the skill file and every link Astryx made that still points at its
+ * folder. A file without the Astryx markers, an edited one, or a symlinked
+ * one, and any link Astryx did not make, are kept.
+ * @param {{home?: string, links?: readonly string[]}} [options]
+ * @returns {import('../../api/init/init.type.mjs').InitUserFile[]}
+ */
+export function removeComputerAgentText({ home, links, }?: {
+    home?: string;
+    links?: readonly string[];
+}): import("../../api/init/init.type.mjs").InitUserFile[];
+/**
+ * Whether the `astryx` a shell would run from this computer's search path is
+ * the Astryx CLI: the first `astryx` found is the one that runs.
+ * @param {{searchPath?: string, platform?: NodeJS.Platform}} [options]
+ * @returns {boolean}
+ */
+export function astryxOnSearchPath(options?: {
+    searchPath?: string;
+    platform?: NodeJS.Platform;
+}): boolean;
+/** The command the computer-level text uses when no host door is set. */
+export const COMPUTER_COMMAND: "astryx";
+/** The install step for the CLI copy the computer-level text relies on. */
+export const COMPUTER_INSTALL_STEP: "npm i -g @astryxdesign/cli";
+/**
+ * Where the skill folder reaches agents that read only their own skills
+ * folder, each relative to the home folder: the agent's skills folder, the
+ * folder that must already exist for it to be used (`null`: always), and how:
+ * `link`, a folder link to the skill folder with a relative target, or `copy`,
+ * a managed copy of the file for an agent whose scanner skips links. Public
+ * agents only. Never a store another tool manages, such as `~/.codex/skills`.
+ * @type {ReadonlyArray<{skills: string, when: string | null, mode: 'link' | 'copy'}>}
+ */
+export const SKILL_LINKS: ReadonlyArray<{
+    skills: string;
+    when: string | null;
+    mode: "link" | "copy";
+}>;
+/**
+ * The commands the text may name: stable entry points every release keeps.
+ * computer-agent-text.test.mjs fails on any other.
+ */
+export const STABLE_COMMANDS: readonly string[];
+/**
+ * What is at one path of the computer-level text.
+ * - `absent`: nothing there.
+ * - `current`: an Astryx file with exactly this release's rendering.
+ * - `differs`: an unedited Astryx file (its recorded hash matches) with
+ *   another rendering, such as another release's.
+ * - `edited`: an Astryx file (it has the markers) whose text no longer
+ *   matches its recorded hash, or that records none: a person changed it.
+ *   Never changed.
+ * - `foreign`: a file without the Astryx markers, a symlink, or something
+ *   other than a regular file. Never changed.
+ * - `linked`, `dangling` (a link only): a link to the skill folder, or one
+ *   whose folder is missing (see linkStateOf).
+ */
+export type ComputerAgentTextState = "absent" | "current" | "differs" | "edited" | "foreign" | "linked" | "dangling";