@theoremjs/studio 0.0.0-stage → 0.3.2

package/setups.mjs

@@ -0,0 +1,170 @@
+/**
+ * The setups a project has, and choosing one of them.
+ *
+ * A setup is a file named `studio.setup.ts`, or `<name>.studio.setup.ts` when a project keeps more
+ * than one. The first is named for the folder it sits in.
+ */
+import { readdirSync } from 'node:fs';
+import path from 'node:path';
+
+const SETUP_FILE = /^(?:(.+)\.)?studio\.setup\.(?:ts|tsx|mts|js|mjs)$/;
+/** Folders that hold installed or built files, never a setup. */
+const SKIPPED = new Set(['node_modules', 'dist', 'build', 'coverage', 'tmp', 'test-results']);
+/** How many folders down from the project a setup is looked for. */
+const DEPTH = 4;
+
+/**
+ * @typedef {{ name: string, file: string }} Setup `file` is relative to the project, with `/`.
+ * @typedef {{ setups: readonly Setup[], at: number, chosen?: Setup, left?: true }} Picker
+ * @typedef {'up' | 'down' | 'choose' | 'leave'} PickerKey
+ */
+
+/**
+ * The setup a file is, or nothing when its name is not a setup's.
+ * @param {string} file relative to the project, with `/`
+ * @param {string} project the project folder's name
+ * @returns {Setup | undefined}
+ */
+export function setupOf(file, project) {
+  const parts = file.split('/');
+  const match = SETUP_FILE.exec(parts[parts.length - 1]);
+  if (!match) return undefined;
+  return { name: match[1] ?? parts[parts.length - 2] ?? project, file };
+}
+
+/**
+ * Every setup among these files, by name and then by path.
+ * @param {readonly string[]} files relative to the project, with `/`
+ * @param {string} project the project folder's name
+ * @returns {Setup[]}
+ */
+export function setupsAmong(files, project) {
+  return files
+    .flatMap((file) => setupOf(file, project) ?? [])
+    .sort((a, b) => a.name.localeCompare(b.name) || a.file.localeCompare(b.file));
+}
+
+/**
+ * The files of a project that could be a setup: everything a few folders down, outside installed,
+ * built and hidden folders.
+ * @param {string} root
+ * @returns {string[]}
+ */
+function projectFiles(root) {
+  const files = [];
+  const walk = (folder, depth) => {
+    for (const entry of readdirSync(path.join(root, folder), { withFileTypes: true })) {
+      const at = folder ? `${folder}/${entry.name}` : entry.name;
+      if (entry.isFile()) files.push(at);
+      else if (
+        entry.isDirectory() &&
+        depth < DEPTH &&
+        !entry.name.startsWith('.') &&
+        !SKIPPED.has(entry.name)
+      ) {
+        walk(at, depth + 1);
+      }
+    }
+  };
+  walk('', 0);
+  return files;
+}
+
+/** @param {string} root @returns {Setup[]} */
+export const findSetups = (root) => setupsAmong(projectFiles(root), path.basename(root));
+
+/**
+ * The setups a builder means by a word: the one at that path, else every one with that name.
+ * @param {readonly Setup[]} setups
+ * @param {string} wanted
+ * @returns {Setup[]}
+ */
+export function setupsNamed(setups, wanted) {
+  const file = path.posix.normalize(wanted.split(path.sep).join('/'));
+  const at = setups.filter((setup) => setup.file === file);
+  return at.length > 0 ? at : setups.filter((setup) => setup.name === wanted);
+}
+
+/** @param {readonly Setup[]} setups @returns {Picker} */
+export const picker = (setups) => ({ setups, at: 0 });
+
+/**
+ * The picker after a key. Up and down stop at the ends.
+ * @param {Picker} state
+ * @param {PickerKey} key
+ * @returns {Picker}
+ */
+export function pick(state, key) {
+  if (key === 'up') return { ...state, at: Math.max(0, state.at - 1) };
+  if (key === 'down') return { ...state, at: Math.min(state.setups.length - 1, state.at + 1) };
+  if (key === 'choose') return { ...state, chosen: state.setups[state.at] };
+  return { ...state, left: true };
+}
+
+/**
+ * The key a keypress is, or nothing when the picker has no use for it.
+ * @param {{ name?: string, ctrl?: boolean }} press
+ * @returns {PickerKey | undefined}
+ */
+export function pickerKey(press) {
+  if (press.ctrl) return press.name === 'c' || press.name === 'd' ? 'leave' : undefined;
+  if (press.name === 'up' || press.name === 'k') return 'up';
+  if (press.name === 'down' || press.name === 'j') return 'down';
+  if (press.name === 'return') return 'choose';
+  if (press.name === 'escape' || press.name === 'q') return 'leave';
+  return undefined;
+}
+
+/**
+ * The list as lines: each setup's name and file, the names in one column.
+ * @param {readonly Setup[]} setups
+ * @param {number} [at] the one the cursor is on
+ * @returns {string[]}
+ */
+export function setupLines(setups, at) {
+  const wide = Math.max(...setups.map((setup) => setup.name.length));
+  return setups.map(
+    (setup, row) => `${row === at ? '›' : ' '} ${setup.name.padEnd(wide)}  ${setup.file}`,
+  );
+}
+
+/**
+ * Asks which setup to open, with the arrow keys. Nothing when the builder leaves.
+ * @param {readonly Setup[]} setups
+ * @param {NodeJS.ReadStream} input a terminal
+ * @param {NodeJS.WriteStream} output
+ * @returns {Promise<Setup | undefined>}
+ */
+export async function chooseSetup(setups, input, output) {
+  const { emitKeypressEvents } = await import('node:readline');
+  const bold = (text) => `\x1b[1m${text}\x1b[22m`;
+  const dim = (text) => `\x1b[2m${text}\x1b[22m`;
+  let state = picker(setups);
+  const draw = (again) => {
+    const lines = setupLines(setups, state.at).map((line, row) =>
+      row === state.at ? bold(line) : line,
+    );
+    // Back to the top of the list, then over it.
+    output.write(
+      `${again ? `\x1b[${String(lines.length + 1)}A` : ''}${lines.join('\n')}\n${dim('↑ ↓ to move, enter to open')}\n`,
+    );
+  };
+  output.write('Which setup?\n');
+  draw(false);
+  emitKeypressEvents(input);
+  input.setRawMode(true);
+  input.resume();
+  return new Promise((resolve) => {
+    const onPress = (_text, press) => {
+      const key = pickerKey(press ?? {});
+      if (!key) return;
+      state = pick(state, key);
+      if (!state.chosen && !state.left) return draw(true);
+      input.off('keypress', onPress);
+      input.setRawMode(false);
+      input.pause();
+      resolve(state.chosen);
+    };
+    input.on('keypress', onPress);
+  });
+}

package/shared-carry.d.ts

@@ -0,0 +1,114 @@
+/**
+ * A change to a value the project's files write once, made on every agent or
+ * tool that shares it. The files hold one value, so the workspace does too.
+ * The same stop names the other code that reads the value, when some does.
+ *
+ * @module
+ */
+import { type ToolSpecDraft } from './draft.ts';
+import type { SettingSite, SourcePlace } from './server/save-wire.ts';
+import { type AgentDraft, type StudioWorkspace } from './workspace.ts';
+/** Where each profile's or tool's shared values are written, by the id or name the files know it by. */
+export type SharedSites = Record<string, readonly SettingSite[]>;
+/** Each agent as it last compiled, by key: its draft then, and the profile that draft compiles to. */
+export type SharedSnapshot = Map<string, {
+    draft: AgentDraft;
+    profile: unknown;
+}>;
+/** Each tool as it last compiled, by key: its draft then, and what that draft registers. */
+export type ToolSnapshot = Map<string, {
+    draft: ToolSpecDraft;
+    tool: unknown;
+}>;
+/** What a change to a shared value reached. */
+export interface SharedReach {
+    /** Each shared place the change is written in, by its site. */
+    sites: number[];
+    /** The constant or function that holds the first of them, and where it is. */
+    name?: string;
+    file: string;
+    line: number;
+    /** The agent that was edited, and the other agents the change was made on, by key. */
+    from: string;
+    agents: string[];
+    /**
+     * The agents that share the value and were left as they are: one with an issue the studio
+     * cannot compile past, or one the change would move in more than this. Save writes the value
+     * once they hold it too.
+     */
+    left: string[];
+    /** Set for a tool's value: the other tools the change was made on, and the ones left as they are, by key. */
+    amongTools?: {
+        made: string[];
+        left: string[];
+    };
+    /** Set when other code reads the value too: each line that reads it. None when the studio cannot name one. */
+    readBy?: SourcePlace[];
+}
+/** A change to tools of the library that other agents allow too: a tool is one thing for all of them. */
+export interface ToolReach {
+    /** The tools changed or removed, by key, and by name as they were. */
+    tools: string[];
+    names: string[];
+    /** The agent the change was made in, and the other agents that allow one of the tools, by key. */
+    from: string;
+    agents: string[];
+}
+export interface SharedCarry {
+    workspace: StudioWorkspace;
+    /** What the next change is read against. */
+    snapshot: SharedSnapshot;
+    /** The same for the tools, when the project's tools share values. */
+    tools?: ToolSnapshot;
+    /** Set when the change reaches past where the builder made it: other agents or tools, or other code. */
+    reach?: SharedReach;
+}
+/**
+ * Each agent of `workspace` as it compiles now. One that does not compile keeps what `before`
+ * holds for it, so a change made while it did not is still read once it does.
+ */
+export declare function sharedSnapshot(workspace: StudioWorkspace, before?: SharedSnapshot): SharedSnapshot;
+/**
+ * `made`, with each change since `good` to a shared value made on every agent that shares it.
+ * A change is carried only when the agent then compiles to that value there and to nothing else
+ * new: otherwise the agent is left as it is, and Save names it.
+ */
+export declare function withSharedCarry(good: SharedSnapshot, made: StudioWorkspace, sites: SharedSites): SharedCarry;
+/**
+ * Each tool of `workspace` as it registers now. One that does not compile keeps what `before`
+ * holds for it, so a change made while it did not is still read once it does.
+ */
+export declare function toolSnapshot(workspace: StudioWorkspace, before?: ToolSnapshot): ToolSnapshot;
+/**
+ * `made`, with each change since `good` to a value tools share made on every tool that shares it:
+ * a schema several tools take, a list they all name. A change is carried only when the tool then
+ * registers with that value there and nothing else new: otherwise the tool is left as it is, and
+ * Save names it. A tool no agent allows is not registered here, so it is not read.
+ */
+export declare function withToolCarry(good: ToolSnapshot, made: StudioWorkspace, sites: SharedSites): {
+    workspace: StudioWorkspace;
+    snapshot: ToolSnapshot;
+    reach?: SharedReach;
+};
+/** What a change from `before` to `made`, made in the agent `from`, does to tools other agents allow. */
+export declare function toolReach(before: StudioWorkspace, made: StudioWorkspace, from: string): ToolReach | undefined;
+/** A line of a file the question names. */
+export interface AskPlace {
+    file: string;
+    line: number;
+}
+export interface Ask {
+    title: string;
+    /** The cause and the effect, with each place in full. */
+    line: string;
+    /** The places `line` names, in the order it names them. */
+    places: AskPlace[];
+}
+/** A place as the question shows it: the file's name and the line. The folders it is in are for whoever asks. */
+export declare function shortPlace({ file, line }: AskPlace): string;
+/** The question's line as its text and the places it names, in the order it says them. */
+export declare function askParts(ask: Ask): Array<string | AskPlace>;
+/** What the builder is asked before a change to a shared value is made: the question, then its cause and effect. */
+export declare function sharedAsk(reach: SharedReach | ToolReach, workspace: StudioWorkspace): Ask;
+/** Whether agreeing to a change makes it on others too: other agents, other tools. */
+export declare function reachesOthers(reach: SharedReach | ToolReach): boolean;