@awebai/oats 0.67.1 → 0.68.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +112 -16
- package/docs/capabilities.md +54 -5
- package/docs/capability-manifest.schema.json +4 -0
- package/docs/design/2026-10-22-module-upgrade.md +192 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +248 -9
- package/docs/desktop.md +316 -63
- package/docs/first-team.md +5 -3
- package/docs/implementation.md +42 -3
- package/docs/integrations.md +16 -4
- package/docs/knowledge.md +44 -27
- package/docs/layers.md +2 -2
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.68.0.md +504 -0
- package/docs/release-notes/v0.68.1.md +102 -0
- package/docs/servers.md +6 -1
- package/docs/souls-and-instances.md +38 -3
- package/docs/tui.md +663 -243
- package/docs/upgrading.md +66 -6
- package/docs/workspaces.md +2 -2
- package/lib/capability-contract.mjs +6 -5
- package/lib/core.mjs +222 -38
- package/lib/instance-events.mjs +1 -1
- package/lib/instance-resolution.mjs +5 -5
- package/lib/instance-upgrade.mjs +1445 -0
- package/lib/materialize.mjs +225 -78
- package/lib/servers.mjs +11 -7
- package/lib/upgrade-state.mjs +101 -0
- package/lib/workspace.mjs +4 -1
- package/lib/worktree.mjs +103 -12
- package/package-catalog.json +5 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +15 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-panel.mjs +6 -2
- package/packages/client/instance-display-name.mjs +18 -0
- package/packages/client/keymap.mjs +89 -45
- package/packages/client/keys-file.mjs +9 -5
- package/packages/client/panel-views.mjs +16 -3
- package/packages/client/spawn-naming.mjs +7 -6
- package/packages/client/spawn-preview-cli.mjs +37 -1
- package/packages/client/spawn-preview-contract.mjs +35 -0
- package/packages/client/spawn-preview.mjs +35 -2
- package/packages/client/team-members.mjs +4 -1
- package/packages/client/workspace-step.mjs +25 -0
- package/packages/tui/README.md +5 -5
- package/packages/tui/lib/actions.mjs +51 -27
- package/packages/tui/lib/client.mjs +4 -2
- package/packages/tui/lib/config.mjs +4 -4
- package/packages/tui/lib/main.mjs +27 -13
- package/packages/tui/lib/model.mjs +143 -21
- package/packages/tui/lib/store.mjs +343 -68
- package/packages/tui/lib/term/keys.mjs +5 -3
- package/packages/tui/lib/term/kitty.mjs +28 -10
- package/packages/tui/lib/term/screen.mjs +15 -6
- package/packages/tui/lib/term/through.mjs +33 -28
- package/packages/tui/lib/views/capabilities.mjs +6 -6
- package/packages/tui/lib/views/frame.mjs +88 -109
- package/packages/tui/lib/views/help.mjs +57 -35
- package/packages/tui/lib/views/instances.mjs +48 -30
- package/packages/tui/lib/views/souls.mjs +9 -8
- package/packages/tui/lib/views/workspaces.mjs +55 -0
- package/skills/oats-getting-started/SKILL.md +92 -43
package/lib/worktree.mjs
CHANGED
|
@@ -19,7 +19,8 @@
|
|
|
19
19
|
* is passed after `--end-of-options` where the git subcommand honours it. The
|
|
20
20
|
* remote URL is recorded, printed and handed to hooks without userinfo (A2). */
|
|
21
21
|
import { execFileSync, spawn as spawnChild, spawnSync } from "node:child_process";
|
|
22
|
-
import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
|
|
22
|
+
import { chmodSync, existsSync, linkSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmdirSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
|
|
23
|
+
import { tmpdir } from "node:os";
|
|
23
24
|
import { basename, dirname, isAbsolute, join, resolve } from "node:path";
|
|
24
25
|
import { checkHolderByHand, ifItDoesNotEnd, lifecycleBusy, nothingAfter, oatsError, OWN_START_REMEDY } from "./errors.mjs";
|
|
25
26
|
import { appendEvent } from "./instance-events.mjs";
|
|
@@ -53,8 +54,8 @@ export function worktreeFetchTimeoutMs(env = process.env) {
|
|
|
53
54
|
/** The git environment of every step: the invoker's, never prompting for credentials. */
|
|
54
55
|
const gitEnv = () => ({ ...process.env, GIT_TERMINAL_PROMPT: "0" });
|
|
55
56
|
/** Run git → { ok, out, err, status }. Never a shell. */
|
|
56
|
-
function git(argv, { timeout = 120_000 } = {}) {
|
|
57
|
-
const r = spawnSync("git", argv, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: gitEnv(), timeout, maxBuffer: 64 * 1024 * 1024 });
|
|
57
|
+
function git(argv, { timeout = 120_000, env = {}, input } = {}) {
|
|
58
|
+
const r = spawnSync("git", argv, { encoding: "utf8", stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], input, env: { ...gitEnv(), ...env }, timeout, maxBuffer: 64 * 1024 * 1024 });
|
|
58
59
|
return { ok: r.status === 0 && !r.error, out: String(r.stdout ?? ""), err: String(r.stderr ?? "").trim() || r.error?.message || "", status: r.status };
|
|
59
60
|
}
|
|
60
61
|
/** Run a git step that changes something (a tree, a ref, the worktree list) as a recorded child:
|
|
@@ -607,6 +608,73 @@ export async function worktreeAdd(homeArg, o = {}) {
|
|
|
607
608
|
|
|
608
609
|
// ---------- remove ----------
|
|
609
610
|
|
|
611
|
+
const manualResidueRemedy = (tree, purpose) => `save any work and remove ${tree} by hand, then run \`oats worktree remove --purpose ${purpose}\` to drop its record`;
|
|
612
|
+
|
|
613
|
+
/** Git removes its admin entry even when deleting ignored output fails. A later remove
|
|
614
|
+
* has no index to ask: compare the surviving files with the recorded branch in a private
|
|
615
|
+
* index, never the clone's index. Missing files are expected after partial deletion. */
|
|
616
|
+
function checkRemovalResidue(clone, tree, rec, refuse) {
|
|
617
|
+
const dotgit = join(tree, ".git");
|
|
618
|
+
let missingGitdir = false;
|
|
619
|
+
try {
|
|
620
|
+
if (lstatSync(dotgit).isFile()) {
|
|
621
|
+
const match = /^gitdir: (.+)\r?\n?$/.exec(readFileSync(dotgit, "utf8"));
|
|
622
|
+
if (match) {
|
|
623
|
+
try { lstatSync(resolve(tree, match[1])); }
|
|
624
|
+
catch (e) { if (e.code === "ENOENT") missingGitdir = true; else throw e; }
|
|
625
|
+
}
|
|
626
|
+
}
|
|
627
|
+
} catch (e) { throw refuse(`the unregistered tree's .git file could not be checked (${e.message}); ${manualResidueRemedy(tree, rec.purpose)}`); }
|
|
628
|
+
if (!missingGitdir) throw refuse(`the unregistered tree has no .git file pointing at a missing gitdir; ${manualResidueRemedy(tree, rec.purpose)}`);
|
|
629
|
+
|
|
630
|
+
const scratch = mkdtempSync(join(tmpdir(), "oats-worktree-remove-"));
|
|
631
|
+
try {
|
|
632
|
+
const env = { GIT_INDEX_FILE: join(scratch, "index") };
|
|
633
|
+
const args = ["-C", clone, "--work-tree", tree];
|
|
634
|
+
const read = git([...args, "read-tree", `refs/heads/${rec.branch}`], { env });
|
|
635
|
+
if (!read.ok) throw refuse(`the recorded branch ${rec.branch} could not be read (${firstLine(read.err)})`);
|
|
636
|
+
// read-tree has no stat cache. Refresh it before diff-files so identical survivors
|
|
637
|
+
// are compared by content; a refresh reporting differences is expected, not a failure.
|
|
638
|
+
const refresh = git([...args, "update-index", "--really-refresh", "--ignore-missing"], { env });
|
|
639
|
+
if (!refresh.ok && refresh.status !== 1) throw refuse(`the surviving files could not be checked (${firstLine(refresh.err)})`);
|
|
640
|
+
const diff = git([...args, "diff-files", "--name-only", "--diff-filter=d", "--ignore-submodules=none", "-z"], { env });
|
|
641
|
+
const deleted = git([...args, "diff-files", "--name-only", "--diff-filter=D", "--ignore-submodules=none", "-z"], { env });
|
|
642
|
+
if (!diff.ok || !deleted.ok) throw refuse(`the surviving files could not be checked (${firstLine(diff.err || deleted.err)})`);
|
|
643
|
+
// Partial deletion can remove .gitignore before its ignored output. Git reads
|
|
644
|
+
// absent per-directory ignore files from the index only with skip-worktree set.
|
|
645
|
+
// Mark deletions after checking modifications, in this private index alone.
|
|
646
|
+
if (deleted.out) {
|
|
647
|
+
const skip = git([...args, "update-index", "--skip-worktree", "-z", "--stdin"], { env, input: deleted.out });
|
|
648
|
+
if (!skip.ok) throw refuse(`the deleted ignore rules could not be read from the temporary index (${firstLine(skip.err)})`);
|
|
649
|
+
}
|
|
650
|
+
const others = git([...args, "ls-files", "--others", "--exclude-standard", "-z"], { env });
|
|
651
|
+
if (!others.ok) throw refuse(`the surviving files could not be checked (${firstLine(others.err)})`);
|
|
652
|
+
const paths = [...new Set([...diff.out.split("\0"), ...others.out.split("\0")].filter(Boolean))];
|
|
653
|
+
if (paths.length) {
|
|
654
|
+
const changed = paths.map((p) => JSON.stringify(p)).join(", ");
|
|
655
|
+
throw Object.assign(oatsError("E_WORKTREE_DIRTY", `the unregistered tree ${tree} has modified or untracked work: ${changed}; save its changes, or discard them, then retry (the record is kept)`), { details: { purpose: rec.purpose, path: tree, git: changed } });
|
|
656
|
+
}
|
|
657
|
+
} finally { rmSync(scratch, { recursive: true, force: true }); }
|
|
658
|
+
}
|
|
659
|
+
|
|
660
|
+
/** Only after Git's clean check, or the retry's branch comparison. lstat and skipping
|
|
661
|
+
* symlinks keep permission changes inside the tree; rm never follows their targets. */
|
|
662
|
+
function removeWritableResidue(tree) {
|
|
663
|
+
const makeWritable = (path) => {
|
|
664
|
+
const st = lstatSync(path);
|
|
665
|
+
if (st.isSymbolicLink()) return;
|
|
666
|
+
chmodSync(path, st.mode | (st.isDirectory() ? 0o700 : 0o200));
|
|
667
|
+
if (st.isDirectory()) for (const name of readdirSync(path)) makeWritable(join(path, name));
|
|
668
|
+
};
|
|
669
|
+
if (!lstatSync(tree).isDirectory()) throw new Error("the recorded tree path is not a directory");
|
|
670
|
+
makeWritable(tree);
|
|
671
|
+
// Recursive rm can delete .git even when another entry fails. Keep the retry
|
|
672
|
+
// marker until every other entry is gone; the record stays until verification.
|
|
673
|
+
for (const name of readdirSync(tree)) if (name !== ".git") rmSync(join(tree, name), { recursive: true, force: true });
|
|
674
|
+
rmSync(join(tree, ".git"), { recursive: true, force: true });
|
|
675
|
+
rmdirSync(tree);
|
|
676
|
+
}
|
|
677
|
+
|
|
610
678
|
/** `oats worktree remove --purpose <p>`: `git worktree remove` (which refuses a dirty tree),
|
|
611
679
|
* the branch kept, no hook, the record dropped. A `creating` record whose adder is gone is
|
|
612
680
|
* rolled back instead. Only recorded trees: a hand-made one is git's to remove.
|
|
@@ -638,27 +706,50 @@ export async function worktreeRemove(homeArg, o = {}) {
|
|
|
638
706
|
return { purpose, path: tree, removed: true, rolledBack: true, branch: rec.branch, branchKept: rb.branchKept, ...(rb.branchKeptReason ? { branchKeptReason: rb.branchKeptReason } : {}), ...(warned.length ? { warnings: warned } : {}) };
|
|
639
707
|
}
|
|
640
708
|
const clone = rec.clone;
|
|
709
|
+
// existsSync follows links: a dangling link is still an entry we must not orphan.
|
|
710
|
+
const treePresent = () => lstatSync(tree, { throwIfNoEntry: false }) !== undefined;
|
|
641
711
|
// Who is attached, asked while the tree is there (a link through an alias resolves only then).
|
|
642
712
|
// The owner's lineage is read under the home's real path: the command may have been given a
|
|
643
713
|
// link to the home, whose name and parents are not the instance's.
|
|
644
714
|
const realHome = realpathOr(home);
|
|
645
|
-
const attached =
|
|
715
|
+
const attached = treePresent() ? attachedToTree(dirname(dirname(dirname(realHome))), basename(realHome), tree) : [];
|
|
646
716
|
const inUse = attached.filter((c) => c.session !== "stopped");
|
|
647
717
|
if (inUse.length) {
|
|
648
718
|
const seen = inUse.map((c) => `${c.instance} (${c.session === "running" ? "its session is running" : "whether its session is running could not be read"})`).join(", ");
|
|
649
719
|
const step = inUse.length === 1 ? `stop it (\`oats instance stop ${inUse[0].instance}\`) or retire it` : "stop each one (`oats instance stop <instance>`) or retire it";
|
|
650
720
|
throw Object.assign(oatsError("E_CHILDREN_RUNNING", `${tree} is the work of ${inUse.length === 1 ? "an attached instance" : "attached instances"}: ${seen}; nothing was removed (the record is kept). To remove the tree, ${step}, then remove again`), { details: { purpose, path: tree, children: inUse } });
|
|
651
721
|
}
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
722
|
+
let started = false;
|
|
723
|
+
const refuse = (reason, gitError) => Object.assign(oatsError("E_WORK_PRESERVATION_FAILED", `${tree}: ${reason}; ${started ? "Git may already have removed files or its registration; resolve the named problem, then retry to finish the removal" : "no files were removed by this command"} (the record is kept)`), { details: { purpose, path: tree, ...(gitError ? { git: gitError } : {}) } });
|
|
724
|
+
const registered = () => {
|
|
725
|
+
const list = git(["-C", clone, "worktree", "list", "--porcelain", "-z"]);
|
|
726
|
+
if (!list.ok) throw refuse(`the worktree registration could not be read (${firstLine(list.err)})`);
|
|
727
|
+
return worktreeFields(list.out, "worktree").map(realpathOr).includes(realpathOr(tree));
|
|
728
|
+
};
|
|
729
|
+
if (treePresent()) {
|
|
730
|
+
if (!lstatSync(tree).isDirectory()) throw refuse("the recorded tree path is not a directory");
|
|
731
|
+
if (!registered()) {
|
|
732
|
+
checkRemovalResidue(clone, tree, rec, refuse);
|
|
733
|
+
} else {
|
|
734
|
+
const status = git(["-C", tree, "status", "--porcelain", "--ignore-submodules=none"]);
|
|
735
|
+
started = true;
|
|
736
|
+
const r = await trackedGit(["-C", clone, "worktree", "remove", "--end-of-options", tree], { track });
|
|
737
|
+
if (!r.ok && registered()) {
|
|
738
|
+
if (status.ok && status.out.trim()) throw Object.assign(oatsError("E_WORKTREE_DIRTY", `git refused to remove ${tree}: ${firstLine(r.err)}; commit and push its changes, or discard them, then retry (the record is kept)`), { details: { purpose, path: tree, git: r.err } });
|
|
739
|
+
throw refuse(`git could not finish removing the tree (${firstLine(r.err)})`, r.err);
|
|
740
|
+
}
|
|
741
|
+
}
|
|
742
|
+
// An unregistered residue is safe only after the check above: Git passed its own
|
|
743
|
+
// clean check in this call, or the retry proved the surviving files against the branch.
|
|
744
|
+
if (treePresent()) {
|
|
745
|
+
started = true;
|
|
746
|
+
try { removeWritableResidue(tree); }
|
|
747
|
+
catch (e) { throw refuse(`its registration is gone but deleting the remaining files failed (${e.message})${lstatSync(join(tree, ".git"), { throwIfNoEntry: false }) ? "" : `; its .git marker is gone too; ${manualResidueRemedy(tree, purpose)}`}`); }
|
|
658
748
|
}
|
|
659
749
|
}
|
|
660
|
-
await trackedGit(["-C", clone, "worktree", "prune"], { track });
|
|
661
|
-
if (
|
|
750
|
+
const pruned = await trackedGit(["-C", clone, "worktree", "prune"], { track });
|
|
751
|
+
if (!pruned.ok) throw refuse(`git worktree prune failed (${firstLine(pruned.err)})`);
|
|
752
|
+
if (treePresent() || registered()) throw refuse("the tree is still present or registered after git worktree remove");
|
|
662
753
|
rmSync(recPath, { force: true });
|
|
663
754
|
// What the removal left each attached instance with (their sessions were stopped).
|
|
664
755
|
const warned = [...claimWarnings, ...attached.map((c) => `${c.instance}: its work was ${tree}, which was removed; its work link ${join(c.home, "work")} now points at a path that is gone`)];
|
package/package-catalog.json
CHANGED
|
@@ -3,12 +3,12 @@
|
|
|
3
3
|
"packages": {
|
|
4
4
|
"oats.okf": {
|
|
5
5
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
6
|
-
"ref": "v5.
|
|
6
|
+
"ref": "v5.3.0",
|
|
7
7
|
"path": "oats-package"
|
|
8
8
|
},
|
|
9
9
|
"oats.aweb": {
|
|
10
10
|
"url": "https://github.com/awebai/oats-aweb.git",
|
|
11
|
-
"ref": "v1.
|
|
11
|
+
"ref": "v1.31.0",
|
|
12
12
|
"path": "oats-package"
|
|
13
13
|
},
|
|
14
14
|
"oats.jira": {
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
},
|
|
29
29
|
"oats.engineering": {
|
|
30
30
|
"url": "https://github.com/awebai/oats-engineering.git",
|
|
31
|
-
"ref": "v1.
|
|
31
|
+
"ref": "v1.13.0",
|
|
32
32
|
"path": "oats-package"
|
|
33
33
|
},
|
|
34
34
|
"oats.cloning": {
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
},
|
|
44
44
|
"oats.framework": {
|
|
45
45
|
"url": "https://github.com/awebai/oats.git",
|
|
46
|
-
"ref": "oats-framework/v1.
|
|
46
|
+
"ref": "oats-framework/v1.14.1",
|
|
47
47
|
"path": "oats-package"
|
|
48
48
|
}
|
|
49
49
|
},
|
|
@@ -73,6 +73,7 @@
|
|
|
73
73
|
"oats.setup": "oats.framework",
|
|
74
74
|
"oats.okf-harvest": "oats.okf",
|
|
75
75
|
"oats.okf-maintenance": "oats.okf",
|
|
76
|
+
"oats.aweb-tasks": "oats.aweb",
|
|
76
77
|
"oats.engineering-expert": "oats.engineering",
|
|
77
78
|
"oats.developer": "oats.engineering",
|
|
78
79
|
"oats.code-review": "oats.engineering",
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@awebai/oats",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.68.1",
|
|
4
4
|
"description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agents",
|
|
@@ -32,6 +32,7 @@ import { validMaxAge, maxAgeArgv } from './deployment-contract.mjs';
|
|
|
32
32
|
import { MACHINE_ID, machineFieldProblem } from './machine-contract.mjs';
|
|
33
33
|
import { kernelMade } from './kernel-made.mjs';
|
|
34
34
|
import { SOUL_COLORS } from './soul-colors.mjs';
|
|
35
|
+
import { NAMING_TIMEOUT_MS } from './spawn-preview-contract.mjs';
|
|
35
36
|
|
|
36
37
|
const ENVELOPE_TIMEOUT_MS = 60_000;
|
|
37
38
|
|
|
@@ -58,6 +59,9 @@ export function parseEnvelope(stdout) {
|
|
|
58
59
|
* silently degrade into different spawn behavior. */
|
|
59
60
|
const SPAWN_ARG_RULES = {
|
|
60
61
|
purpose: { flag: "--purpose", re: /^[a-z0-9][a-z0-9-]*$/i }, // instance-name slug
|
|
62
|
+
// The exact instance name (feature spawn-name): the kernel's instance-name grammar, lowercase,
|
|
63
|
+
// used as given; the kernel refuses the rest of its rule itself (E_INSTANCE_NAME_INVALID). Never with a purpose.
|
|
64
|
+
name: { flag: "--name", re: /^[a-z0-9][a-z0-9-]*$/ },
|
|
61
65
|
repo: { flag: "--repo", re: /^[^-][^\0]*$/ }, // path — anything not option-shaped
|
|
62
66
|
work: { flag: "--work", re: /^(worktree|checkout|attached|workspace|directory)$/ },
|
|
63
67
|
backend: { flag: "--backend", re: /^tmux$/ },
|
|
@@ -92,6 +96,13 @@ export function spawnArgv(agent, workspaceDir, taskFile, opts = {}) {
|
|
|
92
96
|
: "--relative-to requires a relation (child|sibling|parent)");
|
|
93
97
|
e.code = "E_BAD_ARGS"; throw e;
|
|
94
98
|
}
|
|
99
|
+
// A name is the instance's whole name; a purpose is the part after `<soul>-`: one or the other.
|
|
100
|
+
const given = v => v !== undefined && v !== null && v !== "";
|
|
101
|
+
if (given(opts.name) && given(opts.purpose)) { const e = new Error("a spawn takes --name or --purpose, not both"); e.code = "E_BAD_ARGS"; throw e; }
|
|
102
|
+
// --suggest-name on an apply (feature spawn-apply-suggest-name): the machine that spawns names it from its task, so
|
|
103
|
+
// never beside a name or a purpose.
|
|
104
|
+
if (opts.suggestName !== undefined && typeof opts.suggestName !== "boolean") throw Object.assign(new Error("suggestName must be a boolean"), { code: "E_BAD_ARGS" });
|
|
105
|
+
if (opts.suggestName && (given(opts.name) || given(opts.purpose))) throw Object.assign(new Error("--suggest-name chooses the name: it takes no --name or --purpose"), { code: "E_BAD_ARGS" });
|
|
95
106
|
// relativeRoot rides along with the pair only — alone it is meaningless
|
|
96
107
|
if (!hasRef && opts.relativeRoot !== undefined && opts.relativeRoot !== null && opts.relativeRoot !== "") {
|
|
97
108
|
const e = new Error("--relative-root requires --relation and --relative-to");
|
|
@@ -113,6 +124,7 @@ export function spawnArgv(agent, workspaceDir, taskFile, opts = {}) {
|
|
|
113
124
|
if (typeof opts.yolo !== "boolean") throw Object.assign(new Error("yolo must be a boolean"), { code: "E_BAD_ARGS" });
|
|
114
125
|
argv.push(opts.yolo ? "--yolo" : "--no-yolo");
|
|
115
126
|
}
|
|
127
|
+
if (opts.suggestName) argv.push("--suggest-name");
|
|
116
128
|
argv.push("--json");
|
|
117
129
|
return argv;
|
|
118
130
|
}
|
|
@@ -292,7 +304,9 @@ export async function cliSpawn(bin, { agent, workspaceDir, task, ...opts }, io =
|
|
|
292
304
|
let wakeFile;
|
|
293
305
|
try {
|
|
294
306
|
if (wake) { wakeFile = writeTaskFile(JSON.stringify(wake), io); argv.push("--wake-file", wakeFile.file); }
|
|
295
|
-
|
|
307
|
+
// An apply that names its instance makes the kernel's naming call first: its deadline allows for it.
|
|
308
|
+
const timeout = io.timeout ?? (opts.suggestName ? ENVELOPE_TIMEOUT_MS + NAMING_TIMEOUT_MS : undefined);
|
|
309
|
+
return await runJson(bin, argv, { cwd: workspaceDir, exec: io.exec, timeout });
|
|
296
310
|
} finally { wakeFile?.cleanup(); cleanup(); }
|
|
297
311
|
}
|
|
298
312
|
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
// Every candidate is canonicalized to an absolute executable and accepted
|
|
14
14
|
// ONLY if executable and `<bin> version --json` returns the v1 probe:
|
|
15
15
|
// {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
|
|
16
|
-
// Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.
|
|
16
|
+
// Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.69.0 (the band is
|
|
17
17
|
// spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
|
|
18
18
|
// API version — not source adjacency — is authoritative.
|
|
19
19
|
//
|
|
@@ -52,7 +52,7 @@ export const DESKTOP_API = 1;
|
|
|
52
52
|
// carry a `description` for every kind and `<kind> update <id> --description`
|
|
53
53
|
// sets one (feature `automation-descriptions`, which gates the Desktop's
|
|
54
54
|
// summary writes). The Desktop v1 surface is otherwise unchanged.
|
|
55
|
-
export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0,
|
|
55
|
+
export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 69, 0] };
|
|
56
56
|
/** The band as humans read it — derived, never hand-spelled, so the probe
|
|
57
57
|
* rejection reason, the backend's /api status and the degradation card can
|
|
58
58
|
* never disagree with the numbers actually enforced above. */
|
|
@@ -18,7 +18,9 @@ import { retireData } from './retire-state.mjs';
|
|
|
18
18
|
const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
19
19
|
|
|
20
20
|
/** One row per instance of a roster (deployment-data.mjs `deploymentStatusData`): the kernel's row,
|
|
21
|
-
* with `agent`, `description` and `team` from its soul and `agentsRoot` from the roster
|
|
21
|
+
* with `agent`, `description` and `team` from its soul and `agentsRoot` from the roster, and `soulKey`, the
|
|
22
|
+
* agent row's soul key (`key`, feature launch-preference: a string, or null when no instance records a
|
|
23
|
+
* workspace soul), present only when the agent row has `key`.
|
|
22
24
|
* Needs input: a row keeps the kernel's `waitingOnYou` only when this CLI advertises waiting-on-you.
|
|
23
25
|
* Gate on the feature, never the version: a pre-feature kernel emitting the field is dropped. A row
|
|
24
26
|
* without the key stays without it. */
|
|
@@ -27,7 +29,7 @@ export function rosterRows(roster, cli) {
|
|
|
27
29
|
return roster.agents.flatMap((agent) => agent.instances.map(({ waitingOnYou, ...instance }) => ({
|
|
28
30
|
...instance, ...(waitingFeature && waitingOnYou !== undefined ? { waitingOnYou } : {}),
|
|
29
31
|
agent: instance.agent || agent.name, description: agent.description || "",
|
|
30
|
-
team: agent.team || null, agentsRoot: roster.root,
|
|
32
|
+
team: agent.team || null, agentsRoot: roster.root, ...(Object.hasOwn(agent, "key") ? { soulKey: agent.key } : {}),
|
|
31
33
|
})));
|
|
32
34
|
}
|
|
33
35
|
|
|
@@ -93,6 +95,8 @@ export function panelInstance(i) {
|
|
|
93
95
|
// present only when a provider reported one — never synthesized.
|
|
94
96
|
...(i.modules !== undefined ? { modules: i.modules } : {}),
|
|
95
97
|
...(i.soul !== undefined ? { soul: i.soul } : {}),
|
|
98
|
+
// The soul key the instance was spawned from (rosterRows), as the roster reported it: string or null; absent stays absent.
|
|
99
|
+
...(i.soulKey !== undefined ? { soulKey: i.soulKey } : {}),
|
|
96
100
|
...(i.identity !== undefined ? { identity: i.identity } : {}),
|
|
97
101
|
// desktop-facts: the last session start, where the model came from, the messaging identity's address.
|
|
98
102
|
...(i.startedAt !== undefined ? { startedAt: i.startedAt } : {}),
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/** An instance name as words, for display only: the label of an instance row in the Desktop's and the TUI's sidebar
|
|
2
|
+
* (the product owner, 0.68.1: "like normal words with a space between them, with the first word with initial capital
|
|
3
|
+
* letter"). Every `-` is a space, a run of them one space, the ends trimmed, and only the first character upper-cased;
|
|
4
|
+
* every other character stays as it was.
|
|
5
|
+
* `oats-expert-maintainer-lanes` → "Oats expert maintainer lanes", `tui-leader-hint-developer-2` →
|
|
6
|
+
* "Tui leader hint developer 2", `x` → "X", `already Words` → "Already Words".
|
|
7
|
+
* The real name stays wherever it identifies the instance (a title, the hover card, a copy, a search, the accessible
|
|
8
|
+
* name, a tab, the CLI): this is the visible label alone. DOM-free and import-free, with no module state. */
|
|
9
|
+
|
|
10
|
+
/** `name` as words; '' for a non-string or a name with nothing but `-` and spaces. */
|
|
11
|
+
export function instanceDisplayName(name) {
|
|
12
|
+
if (typeof name !== 'string') return '';
|
|
13
|
+
const words = name.replace(/-+/g, ' ').trim();
|
|
14
|
+
if (!words) return '';
|
|
15
|
+
// The first character by code point, so a name that starts outside the BMP is not split.
|
|
16
|
+
const first = String.fromCodePoint(words.codePointAt(0));
|
|
17
|
+
return first.toUpperCase() + words.slice(first.length);
|
|
18
|
+
}
|
|
@@ -17,10 +17,14 @@
|
|
|
17
17
|
* plainKeys(does) -> the plain key ids of an action (empty when it has none)
|
|
18
18
|
* leaderRows() -> LEADER_TABLE
|
|
19
19
|
* chordKey(does, isMac, family) -> the chord's key id on that platform and in that family, or null
|
|
20
|
-
* chordKeyOf(entry, isMac, family) -> the same for a CHORDS row
|
|
20
|
+
* chordKeyOf(entry, isMac, family) -> the same for a CHORDS row (null where the row has none)
|
|
21
|
+
* doesLabel(does) -> an action's label (its LEADER_TABLE row's, else its CHORDS row's), or null
|
|
21
22
|
* paletteKey(does, isMac) -> the palette's own key id on that platform, or null
|
|
22
23
|
*
|
|
23
|
-
* `does` names an action, not a client's code: each client maps it to its own.
|
|
24
|
+
* `does` names an action, not a client's code: each client maps it to its own. Its label, the words a
|
|
25
|
+
* help names it by, is its LEADER_TABLE row's, else its CHORDS row's (`doesLabel`): a CHORDS row carries
|
|
26
|
+
* a label only for an action the leader has no key for. The TUI's help reads it; the Desktop names its
|
|
27
|
+
* actions in its own words (packages/desktop/renderer/leader-keys.mjs). */
|
|
24
28
|
|
|
25
29
|
/** The leader per platform: Ctrl+X on both, as Emacs has it (#1433). Without the kitty keyboard
|
|
26
30
|
* protocol it is one byte, 0x18, in every terminal; pressed twice it sends that byte to the program
|
|
@@ -30,14 +34,18 @@ export const LEADER = Object.freeze({ mac: "ctrl+x", other: "ctrl+x" });
|
|
|
30
34
|
|
|
31
35
|
/** The keys read after the leader, in the TUI's order, and what each does. `terminal`: named in
|
|
32
36
|
* the hint only while a terminal is open. The leader pressed twice is not here: it is the user's
|
|
33
|
-
* key, and each client says what it does.
|
|
37
|
+
* key, and each client says what it does. ↑ and ↓ move to the previous and the next workspace of
|
|
38
|
+
* the sidebar's list (`workspace-previous`, `workspace-next`); the previous and the next instance
|
|
39
|
+
* are the chords' alone (CHORDS `previous`, `next`), which carry their own labels for it. Tab and
|
|
40
|
+
* Shift+Tab go to the next and the previous group of a split, as the chords `group-next` and
|
|
41
|
+
* `group-previous` do. */
|
|
34
42
|
export const LEADER_TABLE = Object.freeze([
|
|
35
43
|
{ keys: ["k", "space"], does: "palette", label: "palette" },
|
|
36
44
|
{ keys: ["1"], does: "instances", label: "instances" },
|
|
37
45
|
{ keys: ["2"], does: "souls", label: "souls" },
|
|
38
46
|
{ keys: ["3"], does: "capabilities", label: "capabilities" },
|
|
39
|
-
{ keys: ["up"], does: "previous", label: "previous
|
|
40
|
-
{ keys: ["down"], does: "next", label: "next
|
|
47
|
+
{ keys: ["up"], does: "workspace-previous", label: "previous workspace" },
|
|
48
|
+
{ keys: ["down"], does: "workspace-next", label: "next workspace" },
|
|
41
49
|
{ keys: ["z"], does: "zoom", label: "zoom", terminal: true },
|
|
42
50
|
{ keys: ["w"], does: "close-terminal", label: "close terminal", terminal: true },
|
|
43
51
|
{ keys: ["left"], does: "tab-previous", label: "previous tab", terminal: true },
|
|
@@ -45,6 +53,7 @@ export const LEADER_TABLE = Object.freeze([
|
|
|
45
53
|
{ keys: ["|"], does: "split-right", label: "split right", terminal: true },
|
|
46
54
|
{ keys: ["-"], does: "split-down", label: "split down", terminal: true },
|
|
47
55
|
{ keys: ["tab"], does: "group-next", label: "next group", terminal: true },
|
|
56
|
+
{ keys: ["shift+tab"], does: "group-previous", label: "previous group", terminal: true },
|
|
48
57
|
{ keys: ["m"], does: "tab-move", label: "move tab", terminal: true },
|
|
49
58
|
{ keys: ["x"], does: "group-close", label: "close group", terminal: true },
|
|
50
59
|
{ keys: ["X"], does: "stop", label: "stop" },
|
|
@@ -92,47 +101,73 @@ export const PLAIN_KEYS = Object.freeze([
|
|
|
92
101
|
].map((entry) => Object.freeze({ ...entry, keys: Object.freeze([...entry.keys]) })));
|
|
93
102
|
|
|
94
103
|
/** The chords: one key that does what the leader then a key does, from every focus, the same in
|
|
95
|
-
* both clients, per platform (`mac
|
|
96
|
-
*
|
|
97
|
-
*
|
|
98
|
-
*
|
|
104
|
+
* both clients, per platform (`mac`) and, on Linux and Windows, per chord family (`alt`, `other`,
|
|
105
|
+
* `shift`: CHORD_FAMILIES). Three have no leader key: `previous` and `next` (the previous / next
|
|
106
|
+
* instance, whose `label` is here, since no LEADER_TABLE row names them) and `edit-instance`. The
|
|
107
|
+
* Desktop's DEFAULT_KEYMAP reads these entries from here (CHORDS_READ, docs/desktop-keyboard.md); the
|
|
108
|
+
* TUI binds the family's ones, and the `mac` ones without `cmd+`, from every focus (docs/tui.md,
|
|
109
|
+
* "Chords"). The leader stays the key that always works: help, the views and the acts (stop,
|
|
110
|
+
* restart, start, retire) are reached by it alone.
|
|
99
111
|
*
|
|
100
|
-
*
|
|
101
|
-
*
|
|
102
|
-
*
|
|
103
|
-
*
|
|
104
|
-
*
|
|
105
|
-
*
|
|
106
|
-
*
|
|
112
|
+
* `alt`, the default family (the product owner's call, 2026-10-22; the maintainer's defaults, f592e979): Alt with
|
|
113
|
+
* a letter or a digit for an action, Alt with an arrow to move between tabs (←/→) and workspaces
|
|
114
|
+
* (↑/↓), Alt+Shift with an arrow between groups (←/→) and instances (↑/↓). These take keys a program
|
|
115
|
+
* in a terminal reads (readline's M-b, M-f and M-digit, an agent's Alt+P); the program still gets
|
|
116
|
+
* each from Esc, then the key, or the user picks Ctrl+Alt (docs/desktop-keyboard.md, the collision
|
|
117
|
+
* table). Alt+letter is ESC then the letter in every terminal, and an Alt arrow has a sequence of its
|
|
118
|
+
* own (`CSI 1;3A`, `CSI 1;4A` with Shift), so all of them reach the TUI with or without the kitty
|
|
119
|
+
* keyboard protocol. A row without an `alt` key keeps its `other` one there.
|
|
120
|
+
*
|
|
121
|
+
* `other`, the Ctrl+Alt family, the option for whoever needs Alt in their programs: Ctrl+Alt with a
|
|
122
|
+
* letter or a digit for an action and Alt+Shift with an arrow to move. It leaves Alt alone, the Alt
|
|
123
|
+
* arrows included: the workspace moves have no chord there (`other: null`, and none in `shift`),
|
|
124
|
+
* so Alt+↑/↓ reach the program in a terminal; the leader's ↑/↓ move between workspaces in every
|
|
125
|
+
* family. A Ctrl+Alt chord reaches the TUI only under the kitty keyboard protocol (ESC then Ctrl+K
|
|
126
|
+
* is what Ctrl+Alt+K sends without it). Its keys are those from before the Alt family, and the
|
|
127
|
+
* previous group, whose Alt+Shift+← is the previous tab's here, is Ctrl+Alt+Shift+A, the next
|
|
128
|
+
* group's Ctrl+Alt+A with Shift.
|
|
107
129
|
*
|
|
108
130
|
* `shift` is the row's key in the Ctrl+Shift family, the option a user picks in keys.json
|
|
109
131
|
* (packages/client/keys-file.mjs) for a terminal that passes Ctrl+Shift apart from Ctrl: foot and
|
|
110
132
|
* Alacritty (docs/tui.md, "Which family for my terminal"). Seven rows move (K palette, P spawn,
|
|
111
133
|
* S workspaces, M zoom, W close, E split right, D split down: the maintainer's cut, a43470ce); the
|
|
112
|
-
* others keep their `other` key
|
|
113
|
-
*
|
|
114
|
-
*
|
|
115
|
-
*
|
|
134
|
+
* others keep their `other` key: the Alt+Shift arrows, since Ctrl+Shift+arrow selects text in
|
|
135
|
+
* inputs and editors; Ctrl+Alt+1–9, since Ctrl+Shift+digit is a shifted symbol on most layouts;
|
|
136
|
+
* the groups and filter, whose Ctrl+Shift A and F a terminal or an agent takes; and edit-instance.
|
|
137
|
+
*
|
|
138
|
+
* On macOS there is no family and `mac` is the only key. The letters and digits are held by ⌘ (⌘⌥
|
|
139
|
+
* for the rows new in phase 3), and the moves between tabs, groups and workspaces by ⌥ with an arrow
|
|
140
|
+
* (the product owner's call, 2026-10-23): ⌥←/→ the tabs, ⌥⇧←/→ the groups, ⌥↑/↓ the workspaces; ⌥⌘↑/↓ stay the
|
|
141
|
+
* instances. ⌥ with a letter or a digit types a character on many layouts (⌥2 is @ on a Spanish
|
|
142
|
+
* one), so no row takes it. ⌥←/→ are the word moves of macOS text fields and of a shell in a
|
|
143
|
+
* terminal: the clients give way in an editable field (docs/desktop-keyboard.md), and the TUI,
|
|
144
|
+
* which binds the `mac` keys without `cmd+`, reads them from every focus. `tab-N` shows the Nth tab
|
|
145
|
+
* of the focused group, `tab-9` its last. The Desktop's Ctrl+Tab, Ctrl+1/2/3 (the stages) and Ctrl+, are the Desktop's own and are
|
|
146
|
+
* not here. */
|
|
116
147
|
export const CHORDS = Object.freeze([
|
|
117
|
-
{ does: "palette", mac: "cmd+k", other: "ctrl+alt+k", shift: "ctrl+shift+k" },
|
|
118
|
-
{ does: "spawn", mac: "cmd+p", other: "ctrl+alt+p", shift: "ctrl+shift+p" },
|
|
119
|
-
{ does: "workspaces", mac: "cmd+alt+o", other: "ctrl+alt+o", shift: "ctrl+shift+s" },
|
|
120
|
-
{ does: "previous", mac: "cmd+alt+up", other: "alt+shift+up" },
|
|
121
|
-
{ does: "next", mac: "cmd+alt+down", other: "alt+shift+down" },
|
|
122
|
-
|
|
123
|
-
{ does: "
|
|
124
|
-
|
|
125
|
-
{ does: "
|
|
126
|
-
{ does: "
|
|
127
|
-
{
|
|
128
|
-
{ does: "
|
|
129
|
-
{ does: "
|
|
130
|
-
{ does: "
|
|
148
|
+
{ does: "palette", mac: "cmd+k", alt: "alt+k", other: "ctrl+alt+k", shift: "ctrl+shift+k" },
|
|
149
|
+
{ does: "spawn", mac: "cmd+p", alt: "alt+p", other: "ctrl+alt+p", shift: "ctrl+shift+p" },
|
|
150
|
+
{ does: "workspaces", mac: "cmd+alt+o", alt: "alt+o", other: "ctrl+alt+o", shift: "ctrl+shift+s" },
|
|
151
|
+
{ does: "previous", mac: "cmd+alt+up", other: "alt+shift+up", label: "previous instance" },
|
|
152
|
+
{ does: "next", mac: "cmd+alt+down", other: "alt+shift+down", label: "next instance" },
|
|
153
|
+
// The Alt family's alone on Linux and Windows: the others leave Alt+↑/↓ to the program.
|
|
154
|
+
{ does: "workspace-previous", mac: "alt+up", alt: "alt+up", other: null, shift: null },
|
|
155
|
+
{ does: "workspace-next", mac: "alt+down", alt: "alt+down", other: null, shift: null },
|
|
156
|
+
{ does: "tab-previous", mac: "alt+left", alt: "alt+left", other: "alt+shift+left" },
|
|
157
|
+
{ does: "tab-next", mac: "alt+right", alt: "alt+right", other: "alt+shift+right" },
|
|
158
|
+
...Array.from({ length: 9 }, (_, i) => ({ does: `tab-${i + 1}`, mac: `cmd+alt+${i + 1}`, alt: `alt+${i + 1}`, other: `ctrl+alt+${i + 1}` })),
|
|
159
|
+
{ does: "zoom", mac: "cmd+alt+z", alt: "alt+z", other: "ctrl+alt+z", shift: "ctrl+shift+m" },
|
|
160
|
+
{ does: "close-terminal", mac: "cmd+w", alt: "alt+w", other: "ctrl+alt+w", shift: "ctrl+shift+w" },
|
|
161
|
+
{ does: "split-right", mac: "cmd+\\", alt: "alt+e", other: "ctrl+alt+e", shift: "ctrl+shift+e" },
|
|
162
|
+
{ does: "split-down", mac: "cmd+shift+\\", alt: "alt+shift+e", other: "ctrl+alt+shift+e", shift: "ctrl+shift+d" },
|
|
163
|
+
{ does: "group-previous", mac: "alt+shift+left", alt: "alt+shift+left", other: "ctrl+alt+shift+a" },
|
|
164
|
+
{ does: "group-next", mac: "alt+shift+right", alt: "alt+shift+right", other: "ctrl+alt+a" },
|
|
165
|
+
{ does: "filter", mac: "cmd+f", alt: "alt+f", other: "ctrl+alt+f" },
|
|
131
166
|
// The Desktop's alone for now (#1421): its name and colour dialog. No leader key; the TUI has no
|
|
132
167
|
// such action, so it binds no key for it (chordKeys skips a `does` it does not handle). Not one of
|
|
133
|
-
// the seven the Ctrl+Shift family moves: Ctrl+Alt+R in both
|
|
134
|
-
{ does: "edit-instance", mac: "cmd+alt+r", other: "ctrl+alt+r" },
|
|
135
|
-
].map((entry) => Object.freeze({ ...entry, shift: entry.shift ?? entry.other })));
|
|
168
|
+
// the seven the Ctrl+Shift family moves: Ctrl+Alt+R in both of those (the maintainer's ruling).
|
|
169
|
+
{ does: "edit-instance", mac: "cmd+alt+r", alt: "alt+r", other: "ctrl+alt+r" },
|
|
170
|
+
].map((entry) => Object.freeze({ ...entry, alt: entry.alt ?? entry.other, shift: entry.shift ?? entry.other })));
|
|
136
171
|
|
|
137
172
|
/** The palette's own keys, read only while the palette is open: there they win over every binding
|
|
138
173
|
* (the Desktop's ⌘N, `app.chooseSoul`; the chords `previous` and `next`), so they are not CHORDS,
|
|
@@ -145,11 +180,12 @@ export const PALETTE_KEYS = Object.freeze([
|
|
|
145
180
|
{ does: "palette-previous-group", mac: "cmd+alt+n", other: "alt+shift+up" },
|
|
146
181
|
].map((entry) => Object.freeze({ ...entry })));
|
|
147
182
|
|
|
148
|
-
/** The chord families on Linux and Windows: the default and the
|
|
149
|
-
* with the name a client shows for each.
|
|
150
|
-
|
|
151
|
-
export const
|
|
152
|
-
export const
|
|
183
|
+
/** The chord families on Linux and Windows: the default, Alt, and the two options (CHORDS `alt`,
|
|
184
|
+
* `other` and `shift`), with the name a client shows for each. A user who never chose binds the
|
|
185
|
+
* default; one who chose Ctrl+Alt keeps it (keys.json `chords`, packages/client/keys-file.mjs). */
|
|
186
|
+
export const CHORD_FAMILIES = Object.freeze(["alt", "ctrl+alt", "ctrl+shift"]);
|
|
187
|
+
export const DEFAULT_CHORD_FAMILY = "alt";
|
|
188
|
+
export const CHORD_FAMILY_LABELS = Object.freeze({ alt: "Alt", "ctrl+alt": "Ctrl+Alt", "ctrl+shift": "Ctrl+Shift" });
|
|
153
189
|
|
|
154
190
|
const NONE = Object.freeze([]);
|
|
155
191
|
|
|
@@ -175,18 +211,26 @@ export function leaderRows() {
|
|
|
175
211
|
}
|
|
176
212
|
|
|
177
213
|
/** The key id of the CHORDS row `entry` on macOS (`true`) or elsewhere, in `family` (CHORD_FAMILIES;
|
|
178
|
-
* anything else is the default), which macOS ignores
|
|
214
|
+
* anything else is the default, Alt), which macOS ignores; null where the row has no key (the
|
|
215
|
+
* workspace moves outside the Alt family). */
|
|
179
216
|
export function chordKeyOf(entry, isMac, family = DEFAULT_CHORD_FAMILY) {
|
|
180
|
-
|
|
217
|
+
if (isMac) return entry.mac ?? null;
|
|
218
|
+
return (family === "ctrl+shift" ? entry.shift : family === "ctrl+alt" ? entry.other : entry.alt) ?? null;
|
|
181
219
|
}
|
|
182
220
|
|
|
183
221
|
/** The key id of the chord that does `does` on macOS (`true`) or elsewhere, in `family` (chordKeyOf),
|
|
184
|
-
* or null when none does. */
|
|
222
|
+
* or null when none does there. */
|
|
185
223
|
export function chordKey(does, isMac, family = DEFAULT_CHORD_FAMILY) {
|
|
186
224
|
const entry = CHORDS.find((each) => each.does === does);
|
|
187
225
|
return entry === undefined ? null : chordKeyOf(entry, isMac, family);
|
|
188
226
|
}
|
|
189
227
|
|
|
228
|
+
/** The label of the action `does`: its LEADER_TABLE row's, else its CHORDS row's, else null (an action
|
|
229
|
+
* no table names in words, such as `edit-instance`, or none). */
|
|
230
|
+
export function doesLabel(does) {
|
|
231
|
+
return LEADER_TABLE.find((row) => row.does === does)?.label ?? CHORDS.find((entry) => entry.does === does)?.label ?? null;
|
|
232
|
+
}
|
|
233
|
+
|
|
190
234
|
/** The key id of the palette's own key that does `does` on macOS (`true`) or elsewhere, or null. */
|
|
191
235
|
export function paletteKey(does, isMac) {
|
|
192
236
|
const entry = PALETTE_KEYS.find((each) => each.does === does);
|
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
/** keys.json, the one preference both clients share about their keys: which chord family they bind
|
|
2
2
|
* on Linux and Windows (packages/client/keymap.mjs CHORD_FAMILIES). It is `config/keys.json` in OATS's
|
|
3
3
|
* own directory of this user, beside the TUI's tui.json, and resolved the same way: `$OATS_HOME_DIR`
|
|
4
|
-
* when that is set and not empty, else `<home>/.oats`. Its shape: `{ "chords": "ctrl+alt" | "ctrl+shift" }`.
|
|
4
|
+
* when that is set and not empty, else `<home>/.oats`. Its shape: `{ "chords": "alt" | "ctrl+alt" | "ctrl+shift" }`.
|
|
5
|
+
* No file, or no `chords` in it, is no choice: the default, Alt. A `chords` written is a choice, and
|
|
6
|
+
* stays one when the default changes (a user who chose Ctrl+Alt keeps it).
|
|
5
7
|
*
|
|
6
8
|
* The file is the clients'; the kernel never reads it. Each client does its own IO and hands the text
|
|
7
9
|
* here: the TUI at its start, the Desktop in its main process, which hands the family to its renderer
|
|
@@ -16,9 +18,11 @@
|
|
|
16
18
|
* Both clients hand over the file's bytes, not their own reading of them, so the same bytes mean the
|
|
17
19
|
* same family in both: UTF-8 (RFC 8259), a byte-order mark ignored, anything else not text.
|
|
18
20
|
*
|
|
19
|
-
* Every way the file can fail means the default,
|
|
21
|
+
* Every way the file can fail means the default, Alt: none is an error the user must clear. An older
|
|
22
|
+
* client, which knows no `alt`, reads `"chords": "alt"` as an unknown value: its own default, with
|
|
23
|
+
* its note. */
|
|
20
24
|
import { join } from "node:path";
|
|
21
|
-
import { CHORD_FAMILIES, DEFAULT_CHORD_FAMILY } from "./keymap.mjs";
|
|
25
|
+
import { CHORD_FAMILIES, CHORD_FAMILY_LABELS, DEFAULT_CHORD_FAMILY } from "./keymap.mjs";
|
|
22
26
|
|
|
23
27
|
/** The most a client reads of the file, in bytes: anything longer is not a keys.json. */
|
|
24
28
|
export const KEYS_LIMIT = 16384;
|
|
@@ -90,11 +94,11 @@ export function chordFamilyFrom(bytes, error = null) {
|
|
|
90
94
|
}
|
|
91
95
|
|
|
92
96
|
/** The line a client shows when keys.json was there and not taken ("keys.json: unknown chords value,
|
|
93
|
-
* using
|
|
97
|
+
* using Alt", the default's label), or null: the file chose the family, or there is none, which is the default
|
|
94
98
|
* with nothing to say. `read` is what chordFamilyFrom answered. */
|
|
95
99
|
export function chordFamilyNote(read) {
|
|
96
100
|
if (!read || read.why === null || read.why === "missing" || !Object.hasOwn(KEYS_WHY, read.why)) return null;
|
|
97
|
-
return `${KEYS_WHY[read.why]}, using
|
|
101
|
+
return `${KEYS_WHY[read.why]}, using ${CHORD_FAMILY_LABELS[DEFAULT_CHORD_FAMILY]}`;
|
|
98
102
|
}
|
|
99
103
|
|
|
100
104
|
/** The text of keys.json with `chords` set to `family`, from the file's current `bytes` (as
|