leglas 1.3.0 → 1.4.0

package/dist/keep.d.ts

@@ -14,16 +14,9 @@ export type KeepPlan = {
     error: string;
 };
 /**
- * Plan the end of an exploration.
- *
- * Exploring is only safe to start because finishing is cheap, and finishing
- * means the winner leaves the ignored directory for real source while the
- * alternatives disappear entirely. Leglas can do this only because it knows
- * where it put those files; anything it did not generate is refused rather than
- * guessed at.
- *
- * The one step left to the user is the import in their own component, for the
- * same reason `leglas new` prints it rather than applying it.
+ * Plan the end of an exploration: the winner moves into real source and the
+ * rest is deleted. Anything Leglas didn't generate is refused, not guessed at.
+ * The import in the user's own component is left to them, as with `leglas new`.
  */
 export declare function planKeep(options: {
     title: string;

package/dist/new.d.ts

@@ -14,10 +14,9 @@ export type NewPlan = {
     instructions: string;
 };
 /**
- * Which shape of param reading to generate. Only the distinction that changes
- * the output is drawn: whether params arrive on the server as a prop, or are
- * read from the URL in the browser. The browser form is the fallback because
- * it works anywhere React does.
+ * Params either arrive on the server as a prop or are read from the URL in the
+ * browser. The browser form is the fallback, since it works anywhere React
+ * does.
  */
 export declare function detectFramework(packageJson: string | null): Framework;
 /** The surface name becomes a query param, so it has to survive a URL intact. */

package/dist/resolve-title.d.ts

@@ -7,13 +7,9 @@ export type Resolved = {
     error: string;
 };
 /**
- * Resolve a name a command was given, and say something useful when it cannot.
- *
- * The message matters more than usual here. A direction renamed in the rail is
- * only renamed on this machine, so the name a user says is often not the name
- * the config spells; that gap is covered by resolving through the rename map.
- * What is left is a name nothing answers to, where the old message ("run
- * leglas list") sent an agent to a listing that would not contain the name
- * either, and the second miss reads as "the direction is gone".
+ * Resolves a name a command was given, or explains why not. Rail renames are
+ * local, so the name a user says is often not the config's; the rename map
+ * covers that. For a name nothing answers to, pointing at leglas list would
+ * just miss again and read as "the direction is gone".
  */
 export declare function resolveOrExplain(input: string, titles: readonly string[], renames: Renames): Resolved;

package/dist/rules.d.ts

@@ -0,0 +1,41 @@
+import type { AddPreview, ShareReach, ShareTunnel } from "./args.js";
+/**
+ * What a command accepts beyond the shape of its arguments, for the parser and
+ * the MCP tools alike. Syntax stays with the parser: unknown flags, missing
+ * values, numbers that are not numbers.
+ */
+export declare const MIN_PORT = 1;
+export declare const MAX_PORT = 65535;
+export declare const MIN_SHOW_WIDTH = 320;
+export declare const MAX_SHOW_WIDTH = 3840;
+export declare const DEFAULT_EXPLORE_COUNT = 3;
+export declare const DEFAULT_SHARE_REACH: ShareReach;
+export declare function portRefusal(flag: string, port: number): string | null;
+export declare function valueRefusal(flag: string): string;
+/**
+ * A preview needs something to show, and every text it carries has to say
+ * something: an empty note or tag is a slip, not a choice.
+ */
+export declare function addRefusal(preview: AddPreview): string | null;
+/**
+ * Stopping takes nothing that would start a share, and a share holds one
+ * direction or a pair. Reach counts only when it was asked for, since it has
+ * a default.
+ */
+export declare function shareRefusal(options: {
+    titles: readonly string[];
+    reach: ShareReach | undefined;
+    tunnel: ShareTunnel | null;
+    stop: boolean;
+    rotate?: boolean;
+    revoke?: string | null;
+}): string | null;
+export declare function linkRefusal(titles: readonly string[]): string | null;
+export declare function widthRefusal(width: number): string | null;
+/** A width or a port only means something for a screenshot. */
+export declare function showRefusal(options: {
+    screenshot: boolean;
+    width: number | null;
+    port: number | null;
+}): string | null;
+export declare function fromRefusal(from: string | undefined): string | null;

package/dist/run-classify.d.ts

@@ -1,11 +1,9 @@
 import type { ClassifyChange } from "./args.js";
 import type { PreviewDeps, PreviewResult } from "./run-previews.js";
 /**
- * Answer where a direction should live, before it is written.
- *
- * Both answers are successes: the point is to be asked, so an agent about to
- * change dependencies or rewrite a shared file learns the checkout route
- * instead of quietly costing the property that makes flipping instant.
+ * Where a direction should live, asked before it's written. Both answers
+ * succeed: the point is that an agent about to change dependencies or rewrite a
+ * shared file learns the checkout route.
  */
 export declare function runClassify(options: {
     changes: ClassifyChange[];

package/dist/run-explore-build.d.ts

@@ -15,12 +15,9 @@ export type ExploreBuildDeps = {
     sleep?: (milliseconds: number) => Promise<void>;
 };
 /**
- * Build a set of directions with the configured agent and wait for it.
- *
- * The work happens in the running Leglas, which owns the switch file, the
- * rail and the renders; this command starts it, reports each direction as it
- * lands and exits 0 only when every one is ready. Leaving it early does not
- * stop the builds, which the interface can still show and stop.
+ * Builds a set with the configured agent and waits. The running Leglas does the
+ * work; this reports each direction as it lands and exits 0 only when all are
+ * ready. Leaving early doesn't stop the builds.
  */
 export declare function runExploreBuild(options: ExploreBuildOptions, deps: ExploreBuildDeps): Promise<{
     exitCode: number;

package/dist/run-explore.d.ts

@@ -2,12 +2,9 @@ export type ExploreDeps = {
     log(line: string): void;
 };
 /**
- * Brief an agent's exploration.
- *
- * Leglas runs no model, and it hands out no taste either: the agent has the
- * product, the surface and the design system in context, which is where taste
- * comes from. This prints the part the agent cannot know: how a set registers
- * and displays here, what the set is for, and how sets fail.
+ * Briefs an agent's exploration. Leglas runs no model and hands out no taste;
+ * this prints only what the agent can't know: how a set registers here, what
+ * it's for and how sets fail.
  */
 export declare function runExplore(options: {
     surface: string;

package/dist/run-init.d.ts

@@ -2,10 +2,9 @@ export type InitDeps = {
     log(line: string): void;
 };
 /**
- * Prepare a project: an AGENTS.md section so any agent entering the repo knows
- * how to author directions, a starter config, and the ignore entry. Adopting
- * Leglas in a repository is what distributes the contract; nothing has to be
- * installed per user.
+ * Prepares a project: an AGENTS.md section on authoring directions, a starter
+ * config and the ignore entry. Committing it is what spreads the contract;
+ * nothing is installed per user.
  */
 export declare function runInit(options: {
     cwd: string;

package/dist/run-link.d.ts

@@ -0,0 +1,18 @@
+export type LinkDeps = {
+    log(line: string): void;
+    error(line: string): void;
+    fetch?: typeof fetch;
+};
+/**
+ * A link for the person to open: the rail, one direction on the stage, or two
+ * side by side. Names resolve the way `share` resolves them, so the name the
+ * rail shows works too.
+ */
+export declare function runLink(options: {
+    titles: string[];
+    port: number | null;
+    json: boolean;
+    cwd: string;
+}, deps: LinkDeps): Promise<{
+    exitCode: number;
+}>;

package/dist/run-log.d.ts

@@ -3,13 +3,9 @@ export type LogDeps = {
     error(line: string): void;
 };
 /**
- * Read what past explorations decided.
- *
- * The entries are plain markdown in a committed directory and are meant to be
- * read that way, in a pull request or on GitHub. This exists because an agent
- * asked to work on a surface should be able to find what was already tried
- * there without being told where to look, and because a person coming back to
- * a project should not have to know the directory's name.
+ * Reads what past explorations decided. The entries are plain markdown meant to
+ * be read on GitHub; this lets an agent or a returning person find them without
+ * knowing the directory.
  */
 export declare function runLog(options: {
     entry: string | null;

package/dist/run-new.d.ts

@@ -6,13 +6,10 @@ export type NewResult = {
     written: string[];
 };
 /**
- * Scaffold a branch point for a surface.
- *
- * Writes only into the gitignored directory and, at most, appends one line to
- * .gitignore. The single change to the user's own source is printed rather
- * than applied: rewriting somebody's component automatically is how a tool
- * breaks a codebase it does not understand, and a wrong edit there costs far
- * more than a line of copying.
+ * Scaffolds a branch point for a surface. Writes only into the ignored
+ * directory, plus at most one .gitignore line. The one change to the user's own
+ * source is printed, not applied: an automatic edit to someone's component
+ * costs far more than a line of copying.
  */
 export declare function runNew(options: {
     surface: string;

package/dist/run-previews.d.ts

@@ -2,6 +2,7 @@ import type { AddPreview } from "./args.js";
 export type PreviewDeps = {
     log(line: string): void;
     error(line: string): void;
+    fetch?: typeof fetch;
 };
 export type PreviewResult = {
     exitCode: number;
@@ -16,10 +17,9 @@ export declare function runList(options: {
     cwd: string;
 }, deps: PreviewDeps): Promise<PreviewResult>;
 /**
- * Hand pending requests to whoever asks. An agent polls this, acts on each
- * prompt, and clears the queue. Leglas runs no model of its own: the user's
- * agent already knows their conventions and design system, which is context
- * no external worker can have.
+ * Hands pending requests to whoever asks: an agent polls this, acts on each
+ * prompt and clears the queue. Leglas runs no model; the user's agent already
+ * knows their conventions.
  */
 export declare function runRequests(options: {
     json: boolean;

package/dist/run-remove.d.ts

@@ -0,0 +1,17 @@
+export type RemoveDeps = {
+    log(line: string): void;
+    error(line: string): void;
+};
+/**
+ * The rail's delete, from the command line: directions this machine registered
+ * leave the registry, and a running rail drops them on its next read. A
+ * direction the config lists is the project's, so it is refused, and one
+ * refusal removes nothing.
+ */
+export declare function runRemove(options: {
+    titles: string[];
+    json: boolean;
+    cwd: string;
+}, deps: RemoveDeps): Promise<{
+    exitCode: number;
+}>;

package/dist/run-share.d.ts

@@ -5,6 +5,10 @@ export type ShareOptions = {
     reach: ShareReach;
     tunnel: ShareTunnel | null;
     stop: boolean;
+    /** End every link and mint one new, through a new tunnel. */
+    rotate?: boolean;
+    /** One link to end, by its address or id. */
+    revoke?: string | null;
     port: number | null;
     json: boolean;
     cwd: string;
@@ -17,19 +21,15 @@ export type ShareDeps = {
     sleep?: (milliseconds: number) => Promise<void>;
 };
 /**
- * How long to wait for a tunnel's public address before handing back the
- * local one. A quick tunnel usually answers in seconds; a minute covers a
- * slow one without leaving a terminal hanging on a tunnel that failed quietly.
+ * How long to wait for a tunnel's public address before handing back the local
+ * one. Quick tunnels answer in seconds; a minute covers a slow one without
+ * hanging on one that failed quietly.
  */
 export declare const TUNNEL_WAIT_MS = 60000;
 /**
- * Share from the terminal what the panel shares from the interface.
- *
- * The share itself is the running Leglas's, through the same endpoints the
- * panel calls, so it carries the same refusals and the same ceiling. What a
- * terminal cannot have is the browser's own view of the rail, so the rail it
- * shares is the project's: every direction in config order, under the names
- * the interface saved.
+ * The panel's share, from the terminal, through the same endpoints, refusals
+ * and ceiling. Without the browser's view of the rail, the rail shared is the
+ * project's: config order, under the names the interface saved.
  */
 export declare function runShare(options: ShareOptions, deps: ShareDeps): Promise<{
     exitCode: number;

package/dist/run-show.d.ts

@@ -4,11 +4,9 @@ export type ShowDeps = {
     fetch?: typeof fetch;
 };
 /**
- * Answer for one direction, for whoever was handed its reference block.
- *
- * Addressing is by config title, which is what every other command takes and
- * what the block quotes, so a renamed direction is still reachable by the name
- * the project knows it by.
+ * Everything about one direction, for whoever was handed its reference block.
+ * Addressed by config title, like every other command, so a renamed direction
+ * is still reachable.
  */
 export declare function runShow(options: {
     title: string;

package/dist/run-watch.d.ts

@@ -3,15 +3,9 @@ export type WatchDeps = {
     error(line: string): void;
 };
 /**
- * Hand change requests to the user's own agent as they arrive.
- *
- * This is the whole live loop: the interface writes a request, watch picks it
- * up, the user's agent does the work with the user's keys and the user's model.
- * Leglas still runs no model of its own. What it adds is locality, so asking
- * for a change no longer means leaving the comparison for a terminal.
- *
- * Resolves when the watcher stops, which is what a signal does, so the caller
- * stays the same shape as every other command.
+ * Hands change requests to the user's own agent as they arrive, with the user's
+ * keys and model; Leglas runs none. Resolves when a signal stops the watcher,
+ * so the caller looks like every other command.
  */
 export declare function runWatch(options: {
     run: string | undefined;

package/dist/run.d.ts

@@ -18,12 +18,9 @@ export type RunResult = {
     stop(): Promise<void>;
 };
 /**
- * Boot Leglas: resolve config, start the server, open the interface.
- *
- * Nothing here is fatal except being unable to bind a port. A missing config,
- * an invalid config, or a dev server that is not running are all reported and
- * survivable, because the user is mid-setup and needs to be told what to fix,
- * not handed a stack trace.
+ * Boots Leglas: resolve config, start the server, open the interface. Only
+ * failing to bind a port is fatal; a missing or invalid config or a stopped dev
+ * server is reported, since the user is mid-setup.
  */
 export declare function run(options: RunOptions & {
     cwd: string;

package/dist/running.d.ts

@@ -8,12 +8,29 @@ export type FoundLeglas = {
     error: string;
 };
 /**
- * The Leglas serving this project, for a command that needs the running one.
- *
- * An explicit port wins; then the record the running server wrote; then the
- * default, since a record can be missing while a server is up (two servers on
- * one project, the newer one gone first). The health answer decides whichever
- * way the port was found, and a Leglas serving another project is not this
- * one: acting on it would act on the wrong project's directions.
+ * The Leglas serving this project: an explicit port, else the server's record,
+ * else the default (a record can be missing while a server is up). Health
+ * decides either way, and a Leglas serving another project is refused.
  */
 export declare function findLeglas(cwd: string, port: number | null, request: typeof fetch): Promise<FoundLeglas>;
+/**
+ * The interface on one direction, or two side by side; none opens the rail.
+ * On localhost, like the address Leglas opens, because the rail keeps its
+ * layout per origin.
+ */
+export declare function interfaceUrl(port: number, titles: readonly string[]): string;
+/**
+ * The titles on the rail a running Leglas serves, as its interface reads them.
+ * They can differ from the files: a branch or file direction registered while
+ * it runs joins only after a restart.
+ */
+export declare function railTitles(port: number, request: typeof fetch): Promise<ReadonlySet<string> | null>;
+export type Rail = {
+    port: number;
+    titles: ReadonlySet<string>;
+};
+/**
+ * This project's running rail, known only from the record its server writes:
+ * without one there is no link to give, and nothing is asked.
+ */
+export declare function recordedRail(cwd: string, request: typeof fetch): Promise<Rail | null>;