@ontrails/trails 0.2.0

package/src/trails/completions-complete.ts

@@ -0,0 +1,236 @@
+/**
+ * `completions __complete` internal trail -- dynamic completion suggestions.
+ *
+ * The static shell scripts emitted by {@link completionsTrail} delegate to this
+ * trail at tab-press time. The trail receives the partial argv that the user
+ * has typed (after the binary name) and returns newline-delimited suggestions
+ * the shell should offer.
+ *
+ * Today the trail knows about two `run` positions:
+ *
+ *  - `trails run <prefix>` — return matching trail IDs.
+ *  - `trails run example <trail-id> <prefix>` — return matching example names
+ *    defined on the resolved trail.
+ *
+ * The `run example` branch loads the trail's owning app at tab-press time so the
+ * suggestions reflect the live trail definition. Unknown trails and no
+ * examples naturally collapse to an empty list; recoverable load failures are
+ * suppressed here because completion must never surface errors back to the
+ * shell mid-keystroke.
+ */
+
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import {
+  renderAppIdCompletions,
+  renderTrailExampleCompletions,
+  renderTrailIdCompletions,
+} from '../completions.js';
+import { parseRunArgv, parseSelectionControls } from '../run-argv.js';
+import { resolveOperatorProjectContext } from './project-context.js';
+
+const EMPTY_SUGGESTIONS = '';
+
+interface CompleteContext {
+  readonly args: readonly string[];
+  readonly rootDir: string;
+  readonly selectedAppId?: string | undefined;
+  readonly selectedModulePath?: string | undefined;
+}
+
+type CompletionHandler = (ctx: CompleteContext) => Promise<readonly string[]>;
+
+/**
+ * Detect whether the user is completing the example-name positional on a
+ * `trails run example` invocation.
+ *
+ * The shell hands us the partial argv with the **last element** as the token
+ * being completed. We recognize the `run example <trail-id> <TAB>` shape when:
+ *
+ *  - the command family is `run example`, and
+ *  - a non-flag positional (the trail ID) follows `example`.
+ *
+ * Returns the trail ID + prefix to complete, or `null` if the cursor is not
+ * in an example-name value position.
+ */
+const detectExampleValueCompletion = (
+  args: readonly string[]
+): { readonly trailId: string; readonly prefix: string } | null => {
+  if (args.length < 3) {
+    return null;
+  }
+  const [subcommand, trailId] = args;
+  if (subcommand !== 'example') {
+    return null;
+  }
+  if (trailId === undefined || trailId.startsWith('-')) {
+    return null;
+  }
+  const prefix = args[2] ?? '';
+  return { prefix, trailId };
+};
+
+/**
+ * Handler for the `trails run` subcommand.
+ *
+ * Two completion positions are recognized:
+ *
+ *  - `trails run example <trail-id> <prefix>` — return example names defined
+ *    on the resolved trail (matching `prefix`, sorted).
+ *  - `trails run <prefix>` — return matching trail IDs.
+ *
+ * Anything else (unknown flag context, a cursor beyond the trail ID, etc.)
+ * returns no suggestions so completed positional values are not suggested
+ * again.
+ */
+const completeRunPosition: CompletionHandler = async ({
+  args,
+  rootDir,
+  selectedAppId,
+  selectedModulePath,
+}) => {
+  const exampleContext = detectExampleValueCompletion(args);
+  if (exampleContext !== null) {
+    const suggestionsResult = await renderTrailExampleCompletions(
+      rootDir,
+      exampleContext.trailId,
+      exampleContext.prefix,
+      selectedAppId,
+      selectedModulePath
+    );
+    return suggestionsResult.unwrapOr([]);
+  }
+  if (args.length !== 1) {
+    return [];
+  }
+  const prefix = args[0] ?? '';
+  return await renderTrailIdCompletions(
+    rootDir,
+    prefix,
+    selectedAppId,
+    selectedModulePath
+  );
+};
+
+const renderSuggestions = (suggestions: readonly string[]): string =>
+  suggestions.join('\n');
+
+const detectAppValueCompletion = (
+  args: readonly string[]
+): { readonly inline: boolean; readonly prefix: string } | null => {
+  const token = args.at(-1) ?? '';
+  const previous = args.at(-2);
+  if (previous === '--app') {
+    return { inline: false, prefix: token };
+  }
+  if (token.startsWith('--app=')) {
+    return { inline: true, prefix: token.slice('--app='.length) };
+  }
+  return null;
+};
+
+/**
+ * Subcommand → handler dispatch table.
+ *
+ * Keep this a pure lookup so adding a new completion target (`run example`,
+ * `--app`, etc.) is a new entry rather than a new branch.
+ *
+ * @remarks As more handlers grow per-token-shape logic (e.g. distinguishing
+ * `--app <TAB>` vs `<trail-id> <TAB>` for the same subcommand), expect this
+ * table to evolve into a sub-table of (token-pattern → completion-fn) per
+ * subcommand or a small parser yielding a discriminated `CompletionContext`
+ * union. Today the single `'run'` entry is small enough that explicit
+ * branching inside `completeRunPosition` is cleaner.
+ */
+const SUBCOMMAND_HANDLERS: Readonly<Record<string, CompletionHandler>> = {
+  run: completeRunPosition,
+};
+
+export const completionsCompleteTrail = trail('completions.__complete', {
+  description:
+    'Internal: emit dynamic completion suggestions for the current partial argv. Invoked by the static shell completion script at tab-press time.',
+  examples: [
+    {
+      description: 'Empty argv yields no suggestions',
+      input: { args: [] },
+      name: 'Empty args',
+    },
+  ],
+  implementation: async (input, ctx) => {
+    const appContext = detectAppValueCompletion(input.args);
+    const typedSelection = parseSelectionControls(input.args);
+    const parsedRun = parseRunArgv(input.args);
+    const selectionRootDir = typedSelection.rootDir ?? input.rootDir;
+    const selectedContextInput = appContext === null ? typedSelection : {};
+    const context = await resolveOperatorProjectContext(
+      {
+        ...selectedContextInput,
+        ...(selectionRootDir === undefined
+          ? {}
+          : { rootDir: selectionRootDir }),
+      },
+      { cwd: ctx.cwd }
+    );
+    if (context.isErr()) {
+      return context;
+    }
+    const rootDir = context.value.projectRoot;
+    const selectedAppId =
+      context.value.selectedExtent === 'configured-app'
+        ? context.value.app.id
+        : undefined;
+    const selectedModulePath =
+      context.value.selectedExtent !== 'workspace' &&
+      context.value.app.moduleSource === 'module'
+        ? context.value.app.modulePath
+        : undefined;
+
+    if (appContext !== null) {
+      const suggestions = await renderAppIdCompletions(
+        rootDir,
+        appContext.prefix
+      );
+      return Result.ok(
+        renderSuggestions(
+          appContext.inline
+            ? suggestions.map((suggestion) => `--app=${suggestion}`)
+            : suggestions
+        )
+      );
+    }
+
+    const [subcommand] = input.args;
+    if (subcommand === undefined) {
+      return Result.ok(EMPTY_SUGGESTIONS);
+    }
+
+    const handler = SUBCOMMAND_HANDLERS[subcommand];
+    if (handler === undefined) {
+      return Result.ok(EMPTY_SUGGESTIONS);
+    }
+
+    const suggestions = await handler({
+      args: parsedRun.positionals,
+      rootDir,
+      selectedAppId,
+      selectedModulePath,
+    });
+    return Result.ok(renderSuggestions(suggestions));
+  },
+  input: z.object({
+    args: z
+      .array(z.string())
+      .readonly()
+      .describe(
+        'Partial argv after the binary name; the last element is the token being completed'
+      ),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+  }),
+  intent: 'read',
+  output: z
+    .string()
+    .describe(
+      'Newline-delimited suggestions the shell should offer for the current token'
+    ),
+});

package/src/trails/completions.ts

@@ -0,0 +1,47 @@
+/**
+ * `completions` trail -- Print a shell completion script for the `trails` CLI.
+ *
+ * The trail's responsibility is small: render a static shell script that, when
+ * sourced by the user's shell, registers a tab-completion handler that
+ * delegates to `trails completions __complete <args...>` for the live
+ * suggestions. See {@link renderCompletionScript} for the per-shell shape.
+ */
+
+import { trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { renderCompletionScript } from '../completions.js';
+
+const COMPLETIONS_BIN_NAME = 'trails';
+
+export const completionsTrail = trail('completions', {
+  args: ['shell'],
+  description:
+    'Print a shell completion script for the trails CLI; pipe into your shell rc to register tab-completion',
+  examples: [
+    {
+      description: 'Render a bash completion script',
+      input: { shell: 'bash' },
+      name: 'Render bash completion',
+    },
+    {
+      description: 'Render a zsh completion script',
+      input: { shell: 'zsh' },
+      name: 'Render zsh completion',
+    },
+    {
+      description: 'Render a fish completion script',
+      input: { shell: 'fish' },
+      name: 'Render fish completion',
+    },
+  ],
+  implementation: async (input) =>
+    renderCompletionScript(input.shell, COMPLETIONS_BIN_NAME),
+  input: z.object({
+    shell: z
+      .enum(['bash', 'zsh', 'fish'])
+      .describe('Target shell flavor for the completion script'),
+  }),
+  intent: 'read',
+  output: z.string(),
+});

package/src/trails/config-explain.ts

@@ -0,0 +1,43 @@
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { resolveOperatorProjectContext } from './project-context.js';
+import {
+  operatorProjectContextOutput,
+  operatorProjectContextOutputSchema,
+} from './project-context-output.js';
+
+const configExplainInputSchema = z.object({
+  app: z.string().optional().describe('Configured workspace app ID'),
+  rootDir: z.string().optional().describe('Workspace root directory'),
+});
+
+const configExplainOutputSchema = z.object({
+  configPath: z.string().nullable(),
+  project: operatorProjectContextOutputSchema,
+});
+
+export const configExplainTrail = trail('config.explain', {
+  description: 'Explain static Trails project and app identity',
+  examples: [
+    {
+      input: {},
+      name: 'Explain project identity from the current app context',
+    },
+  ],
+  implementation: async (input, ctx) => {
+    const context = await resolveOperatorProjectContext(input, {
+      cwd: ctx.cwd,
+    });
+    if (context.isErr()) {
+      return context;
+    }
+    return Result.ok({
+      configPath: context.value.identity.configPath ?? null,
+      project: operatorProjectContextOutput(context.value),
+    });
+  },
+  input: configExplainInputSchema,
+  intent: 'read',
+  output: configExplainOutputSchema,
+});