castle-web-cli 0.4.212 → 0.4.214
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/dist/agent-prompts.d.ts +1 -0
- package/dist/agent-prompts.js +28 -6
- package/dist/agent.js +33 -2
- package/dist/cloudGit.d.ts +254 -0
- package/dist/cloudGit.js +1687 -0
- package/dist/cloudGitServe.d.ts +41 -0
- package/dist/cloudGitServe.js +318 -0
- package/dist/cover-bridge/play-cover-bridge.js +2 -0
- package/dist/externalSourcemaps.js +2 -1
- package/dist/gitRemote.d.ts +4 -1
- package/dist/gitRemote.js +4 -2
- package/dist/ide.js +52 -7
- package/dist/index.js +149 -2
- package/dist/playCover/bridge.d.ts +6 -0
- package/dist/playCover/bridge.js +159 -0
- package/dist/playCover/builtins.d.ts +29 -0
- package/dist/playCover/builtins.js +189 -0
- package/dist/playCover/capture.d.ts +53 -0
- package/dist/playCover/capture.js +419 -0
- package/dist/playCover/clone.d.ts +40 -0
- package/dist/playCover/clone.js +317 -0
- package/dist/playCover/engine.d.ts +37 -0
- package/dist/playCover/engine.js +76 -0
- package/dist/playCover/errors.d.ts +6 -0
- package/dist/playCover/errors.js +18 -0
- package/dist/playCover/images.d.ts +21 -0
- package/dist/playCover/images.js +180 -0
- package/dist/playCover/instrument.d.ts +49 -0
- package/dist/playCover/instrument.js +334 -0
- package/dist/playCover/protocol.d.ts +14 -0
- package/dist/playCover/protocol.js +139 -0
- package/dist/playCover/rasterize.d.ts +21 -0
- package/dist/playCover/rasterize.js +408 -0
- package/dist/playCover/resources.d.ts +31 -0
- package/dist/playCover/resources.js +823 -0
- package/dist/playCover/scratchCanvas.d.ts +4 -0
- package/dist/playCover/scratchCanvas.js +16 -0
- package/dist/playCover/textSamples.d.ts +36 -0
- package/dist/playCover/textSamples.js +412 -0
- package/dist/playCover/validate.d.ts +79 -0
- package/dist/playCover/validate.js +883 -0
- package/dist/playCover/verify.d.ts +56 -0
- package/dist/playCover/verify.js +578 -0
- package/dist/playCover/verifyRecord.d.ts +71 -0
- package/dist/playCover/verifyRecord.js +243 -0
- package/dist/playCoverGate.d.ts +4 -0
- package/dist/playCoverGate.js +57 -0
- package/dist/playCoverPlacement.d.ts +11 -0
- package/dist/playCoverPlacement.js +110 -0
- package/dist/serve.d.ts +1 -0
- package/dist/serve.js +35 -17
- package/dist/shell/assets/index-BPhS3Ysy.css +1 -0
- package/dist/shell/assets/{index-DzLbNBc7.js → index-BcslKMfS.js} +94 -92
- package/dist/shell/index.html +2 -2
- package/package.json +2 -2
- package/dist/shell/assets/index-BCrgYh76.css +0 -1
package/dist/agent-prompts.d.ts
CHANGED
|
@@ -123,6 +123,7 @@ export declare function buildTaskPrompt(opts: {
|
|
|
123
123
|
siblings?: PromptSibling[];
|
|
124
124
|
plan?: TaskPlanOpts;
|
|
125
125
|
playtest?: boolean;
|
|
126
|
+
git?: boolean;
|
|
126
127
|
}): string;
|
|
127
128
|
export declare const CLAUDE_TASK_SYSTEM_REMINDER = "Castle background task agent: work autonomously to completion -- never pause to ask questions or wait for confirmation; finish the task end-to-end, then stop. Prefer the quickest viable change that fully does the job.";
|
|
128
129
|
export declare const MUSE_TASK_ADDENDUM = "Kit code rules for this deck. The kit guide documents every API you need; use exactly the names and signatures it gives and nothing else. Do not guess at APIs: no typeof checks on methods, no ?. or ?? fallbacks on documented objects, no try/catch around ordinary calls, no alternate spellings of a callback. One mechanism per feature, chosen for what the task asks (a tap on the actor is its onTap; a tap anywhere on the card is the pointer checked in update; a contact is onCollisionEnter): use that one and never also scan for the same event another way. Props come from defaultProps, so never repeat a default with ?? value. Find actors by the behavior or id the task names; never sniff ids like 'player' or 'ball' as fallbacks. Read the guide's gotchas for every API you use and follow them. Reference only files that exist in the deck tree or that you create in this task. Build everything the task names and only that: no extra input methods, actors, or polish it did not mention.";
|
package/dist/agent-prompts.js
CHANGED
|
@@ -934,6 +934,7 @@ export function userTurnInstruction(opts) {
|
|
|
934
934
|
return parts.join("\n\n");
|
|
935
935
|
}
|
|
936
936
|
export function buildTaskPrompt(opts) {
|
|
937
|
+
const save = taskSaveWording(opts.git === true);
|
|
937
938
|
const deps = opts.depsSummary
|
|
938
939
|
? `\n\nThis task waited on earlier tasks:\n${opts.depsSummary}\n`
|
|
939
940
|
: "";
|
|
@@ -972,8 +973,8 @@ export function buildTaskPrompt(opts) {
|
|
|
972
973
|
// -- blind whole-file rewrites made parallel agents clobber each other's
|
|
973
974
|
// edits. Read-then-edit is slower but safe; that is the right tradeoff.)
|
|
974
975
|
const wrapUpList = opts.plan
|
|
975
|
-
?
|
|
976
|
-
:
|
|
976
|
+
? `the 90-progress write, the \`castle-web ${save.command}\` for your paths, writing the notes file, and the handoff lines`
|
|
977
|
+
: `the 90-progress write, the \`castle-web ${save.command}\` for your paths, and writing the notes file`;
|
|
977
978
|
const wrapUp = `\n- Wrap up in ONE tool call, not several: once your last file edit is done, combine ${wrapUpList} into a single shell command (\`;\`-separated so the notes land even if an earlier part hiccups). Then stop -- no extra turns after it.`;
|
|
978
979
|
return `You are a background build agent for the Castle deck "${opts.deckLabel}" (current directory). A separate conversation agent dispatched you with one task. Follow the deck's CLAUDE.md / AGENTS.md conventions. Do not reload the served deck -- the person applies your changes when they are ready. \`npm run restart\` exists, but it is HIGHLY flow breaking: it reloads every panel they have open, including the one they are working in. Use it only when a change clearly requires restarting their whole experience.${quickReference}${layout}
|
|
979
980
|
|
|
@@ -989,13 +990,13 @@ Operating rules:
|
|
|
989
990
|
- Do this one task completely, then stop. Do not expand scope.
|
|
990
991
|
- A fix that comes down to choosing a new number for a value already in the code is a tune, and a tune is a guess the user will keep adjusting. Make that value a key in the file's \`PARAMS\` object as part of the same edit -- the new value as its default, read through \`PARAMS.key\` at the use site, a \`PARAMS_META\` range where one is obvious -- so it reaches the Parameters panel and your notes can link it. Move only the value you tuned, not the file's other constants, and only a value the whole deck shares: a setting each placed thing carries for itself, so two of them can differ, stays where the deck's guide puts it and never goes in \`PARAMS\`. A number the user stated goes in the same way, set exactly as they said it.
|
|
991
992
|
- If the task is to SHOW HOW something is done or to give an example, answer it -- in your streamed output and notes, with a standalone snippet if that helps -- and do NOT insert a demo behavior, blueprint, or actor into their scene; that only happens when the user asked for it in their game. Anything you did add to a scene must be named in your notes by file path and by the actor or blueprint it attached to, so they can find it and take it out.${planRules}
|
|
992
|
-
|
|
993
|
+
${save.rule}
|
|
993
994
|
- Overlap with the other agents working in this deck is fine and expected -- do not try to avoid it or wait for them. Saving only your own paths is all that is asked of you; nothing anyone has written is lost by your save.
|
|
994
995
|
- NEVER run \`restore-version\`. Going back to an earlier version is the user's decision alone -- not yours, not even to undo your own work. If your change is wrong, fix it forward.
|
|
995
996
|
- The deck's CLI is \`castle-web <command>\`, run in this directory. The commands that are yours:
|
|
996
997
|
- \`list-versions [version]\` -- the deck's version history, newest first (a version argument lists from there).
|
|
997
998
|
- \`show-version <version>\` -- what one version changed, as diffs of just those files. Reading history is free; use it when you need to know what recent work actually did.
|
|
998
|
-
-
|
|
999
|
+
- ${save.listing}
|
|
999
1000
|
- \`install\` -- npm install for the deck, after you add a dependency to \`package.json\`.
|
|
1000
1001
|
- \`fork-import-file <imports/...>\` and \`revert-import-file <imports/...>\` -- take or drop this deck's own version of one imported file (see below).
|
|
1001
1002
|
- \`screenshot [--out FILE]\` -- one frame of the running deck. The verification rule above still holds: rarely worth the time it costs the user.
|
|
@@ -1008,7 +1009,7 @@ Operating rules:
|
|
|
1008
1009
|
- A forked file exists on disk TWICE, and reading or grepping finds both copies. \`forks/<alias>/<path>\` is the live one -- edit that one. \`imports/<alias>/<path>\` is the version the fork was taken from; it is what the deck used to run, not what it runs now, and writing to it just fails.
|
|
1009
1010
|
- Other task agents may be editing this same deck IN PARALLEL. When you change an existing file, READ it first and make a targeted edit to just the part you need -- never overwrite a whole file you have not read. A blind full-file rewrite clobbers other agents' in-flight changes. Being a bit slower and careful here is the right tradeoff.
|
|
1010
1011
|
- NEVER revert, replace, or re-scaffold the deck's scenes, scripts, or behaviors back to kit, starter, or imported content, and never delete or rewrite a whole scene as a way to diagnose a problem -- that file IS the person's game, and a rewrite destroys work no one asked you to touch. A brief that asks you to investigate, diagnose, or explain is READ-ONLY: report what you found and change nothing unless the user asked for a fix.
|
|
1011
|
-
|
|
1012
|
+
${save.before}
|
|
1012
1013
|
- How the code should read: decks get opened by strangers copying the pattern, so write for a first-time reader. Name things in words -- \`connection\`, not \`conn\`; \`runtime\`, not \`rt\`. A name that needs a comment to decode is the wrong name.
|
|
1013
1014
|
- Order a file: data shapes first, then classes, then the functions over that data, so the reader meets the shape before the code that moves it.
|
|
1014
1015
|
- Comments say what a thing IS and how the system works, declaratively. Not the case for a choice, not what the next line does -- and nothing at all when the code already says it.
|
|
@@ -1030,7 +1031,28 @@ phase: wiring the paddle to touch
|
|
|
1030
1031
|
- Before finishing, write ${opts.notesPath}: a tiny test guide for the PLAYER -- AT MOST 2-3 bullets (markdown \`- \` lines), each ONE short phrase: what to try and what should happen. NO code, NO API or "integration contract" detail, and no tour of how you built it -- that part is for you, not them. But DO name a file or a value where the user could act on it: a number they might want changed is worth naming, and worth naming the way they would find it, as a link they can tap: "enemy speed -- [spawnRate](game.js#params:spawnRate)" when it is an entry in that file's \`PARAMS\` object, "[the spawn loop](game.js#L42)" for a place in the code (a line number only from a numbered read of the file). Occasionally one bullet may run a little longer, but default to terse. Mention a blocker only if you hit one. The user reads this verbatim to check your work.
|
|
1031
1032
|
- Your final message -- the text after your wrap-up call -- is shown to the user under those notes once the task ends. It is the record of what you did for someone who did not watch the stream, so make it a short plain account: what changed and where (files as tappable links, the same forms as above), the mechanism you chose and why, and any call you made where the brief left a choice. A few sentences or a few short bullets. No signal block, no list of the steps you ran, and do not restate the notes.${wrapUp}
|
|
1032
1033
|
- If you are truly blocked, write the blocker to the notes file and stop rather than guessing wildly.
|
|
1033
|
-
- Never touch files under .castle/ other than ${opts.plan ? "those three paths" : "those two paths"}.
|
|
1034
|
+
- Never touch files under .castle/ other than ${opts.plan ? "those three paths" : "those two paths"}. ${save.store}`;
|
|
1035
|
+
}
|
|
1036
|
+
// How a task agent records its work: a version in the deck's own store, or a
|
|
1037
|
+
// commit when the deck is on git. The version wording is the prompt's original
|
|
1038
|
+
// text, unchanged.
|
|
1039
|
+
function taskSaveWording(git) {
|
|
1040
|
+
if (!git) {
|
|
1041
|
+
return {
|
|
1042
|
+
command: "save-version",
|
|
1043
|
+
rule: '- SAVE A VERSION when your change is done, so the user can see and undo it: `castle-web save-version -m "<short description of what you changed>" <each path you touched>`. Name those paths explicitly -- a bare `save-version` with no paths records the WHOLE deck, including files a sibling agent is still working on. One version for the whole task, at the end; not one per file.',
|
|
1044
|
+
listing: '`save-version -m "<message>" <paths...>` -- as above: your own paths, named explicitly, once at the end.',
|
|
1045
|
+
before: '- Before any change that overwrites or deletes MORE THAN ONE existing file of theirs, save a version first so they can restore: `castle-web save-version -m "<what is about to change>" <those paths>`. That is on top of the end-of-task version below, not instead of it.',
|
|
1046
|
+
store: "(The version store lives there too, but you never edit it by hand -- `castle-web save-version` writes it for you.)",
|
|
1047
|
+
};
|
|
1048
|
+
}
|
|
1049
|
+
return {
|
|
1050
|
+
command: "commit",
|
|
1051
|
+
rule: '- COMMIT when your change is done, so the user can see and undo it: `castle-web commit --reason task -m "<short description of what you changed>" <each path you touched>`. Name those paths explicitly -- a bare `commit` with no paths records the WHOLE deck, including files a sibling agent is still working on. One commit for the whole task, at the end; not one per file. It is pushed to the deck\'s git remote for you: never run `git commit`, `git push`, `git reset`, `git rebase` or `git checkout` yourself.',
|
|
1052
|
+
listing: '`commit --reason task -m "<message>" <paths...>` -- as above: your own paths, named explicitly, once at the end.',
|
|
1053
|
+
before: '- Before any change that overwrites or deletes MORE THAN ONE existing file of theirs, commit them first so they can restore: `castle-web commit --reason task -m "<what is about to change>" <those paths>`. That is on top of the end-of-task commit below, not instead of it.',
|
|
1054
|
+
store: "(The deck's history is git, in .git -- you never edit it by hand; `castle-web commit` writes it for you.)",
|
|
1055
|
+
};
|
|
1034
1056
|
}
|
|
1035
1057
|
// Appended to claude task agents' system prompt (portable replacement for the
|
|
1036
1058
|
// machine-specific /goal slash command): commit to autonomous completion.
|
package/dist/agent.js
CHANGED
|
@@ -45,6 +45,8 @@ import { createPlaytestBrowserManager, } from './native/playtest-browser.js';
|
|
|
45
45
|
import { createPlaywrightPlaytestExecutor } from './native/playtest-executor.js';
|
|
46
46
|
import { createRemotePlaytestExecutor } from './native/playtest-remote.js';
|
|
47
47
|
import { runPlaytest, } from './native/playtest.js';
|
|
48
|
+
import { cloudGitMode } from './cloudGit.js';
|
|
49
|
+
import { createServeGitHooks } from './cloudGitServe.js';
|
|
48
50
|
export const AGENT_WS_PATH = '/__castle/agent';
|
|
49
51
|
const DEFAULT_SETTINGS = {
|
|
50
52
|
// Both roles run the claude CLI routed through OpenRouter at the slug below.
|
|
@@ -2144,6 +2146,7 @@ async function runTaskAgentIn(ctx, task) {
|
|
|
2144
2146
|
quickReference: quickReferenceFor(ctx.deckDir, deckGuide, 'task'),
|
|
2145
2147
|
plan: taskPlanOpts(ctx.deckDir, task.item, ctx.finishedWork),
|
|
2146
2148
|
siblings: ctx.siblings,
|
|
2149
|
+
git: cloudGitMode(ctx.deckDir),
|
|
2147
2150
|
});
|
|
2148
2151
|
// No /goal wrapper: it makes a fresh evaluator re-check the WHOLE task
|
|
2149
2152
|
// prompt (including user-only "done when you reach wave 5"-style play
|
|
@@ -3749,6 +3752,14 @@ function onRouterQueueSettled(ctx, retryable) {
|
|
|
3749
3752
|
}
|
|
3750
3753
|
broadcastQueueState(ctx);
|
|
3751
3754
|
maybeStartRouterQueueTurn(ctx);
|
|
3755
|
+
if (!state.routerRunning) {
|
|
3756
|
+
try {
|
|
3757
|
+
ctx.onIdle?.();
|
|
3758
|
+
}
|
|
3759
|
+
catch (err) {
|
|
3760
|
+
console.error(`[router] onIdle threw: ${err instanceof Error ? err.message : String(err)}`);
|
|
3761
|
+
}
|
|
3762
|
+
}
|
|
3752
3763
|
}
|
|
3753
3764
|
// Auto-interrupt ("fold") a pre-text router turn into the very message that
|
|
3754
3765
|
// triggered it: the turn hasn't produced anything visible yet, so restarting
|
|
@@ -3941,6 +3952,12 @@ function makePlaytestRunner(deps) {
|
|
|
3941
3952
|
return result;
|
|
3942
3953
|
};
|
|
3943
3954
|
}
|
|
3955
|
+
// No task agent running or waiting its turn: the moment the board's work is all on disk.
|
|
3956
|
+
function taskBoardIdle(taskStore) {
|
|
3957
|
+
return !taskStore
|
|
3958
|
+
.sorted()
|
|
3959
|
+
.some((t) => t.status === 'running' || (t.status === 'waiting' && !t.acknowledged));
|
|
3960
|
+
}
|
|
3944
3961
|
export function createAgentServer(opts) {
|
|
3945
3962
|
const { deckDir, deckLabel } = opts;
|
|
3946
3963
|
const welcomeMessage = readWelcomeMessage(deckDir) || DEFAULT_WELCOME_MESSAGE;
|
|
@@ -4031,6 +4048,15 @@ export function createAgentServer(opts) {
|
|
|
4031
4048
|
};
|
|
4032
4049
|
const taskFeeds = createTaskFeeds(broadcast, tasksDir);
|
|
4033
4050
|
const messageThinking = createMessageThinking(broadcast);
|
|
4051
|
+
// Git in the cloud sandbox (CASTLE_GIT=on): commits at turn and task-board ends, and a
|
|
4052
|
+
// merge conflict becomes a router turn. Null with git off.
|
|
4053
|
+
const gitHooks = createServeGitHooks({
|
|
4054
|
+
deckDir,
|
|
4055
|
+
addLog,
|
|
4056
|
+
boardIdle: () => taskBoardIdle(taskStore),
|
|
4057
|
+
routerBusy: () => routerQueue.isRunning(),
|
|
4058
|
+
enqueueInstruction: (text) => routerQueue.handleUserMessage(text, undefined, undefined, undefined, true),
|
|
4059
|
+
});
|
|
4034
4060
|
const taskStore = createTaskStore({
|
|
4035
4061
|
deckDir,
|
|
4036
4062
|
deckLabel,
|
|
@@ -4042,9 +4068,12 @@ export function createAgentServer(opts) {
|
|
|
4042
4068
|
playtest,
|
|
4043
4069
|
// Task lifecycle stays on the board only -- log lines for it were spam.
|
|
4044
4070
|
onUpdate: (task) => broadcast({ type: 'task-update', task: asClientTask(task, opts.signPath) }),
|
|
4045
|
-
onStarted: () =>
|
|
4071
|
+
onStarted: () => gitHooks?.taskStarted(),
|
|
4046
4072
|
onRetry: (task, attempt) => addLog(`agent died, retrying (${attempt}/${MAX_TASK_ATTEMPTS}): ${task.title}`),
|
|
4047
|
-
onFinished: (task) =>
|
|
4073
|
+
onFinished: (task) => {
|
|
4074
|
+
taskFeeds.persist(task);
|
|
4075
|
+
gitHooks?.taskFinished(task.title, task.status === 'done');
|
|
4076
|
+
},
|
|
4048
4077
|
onFeed: (task, entry) => taskFeeds.push(task, entry),
|
|
4049
4078
|
});
|
|
4050
4079
|
// The mid-run send queue (queue-by-default, "send now"/Stop interrupt, epoch
|
|
@@ -4061,6 +4090,7 @@ export function createAgentServer(opts) {
|
|
|
4061
4090
|
messageThinking,
|
|
4062
4091
|
messages,
|
|
4063
4092
|
settings,
|
|
4093
|
+
onIdle: () => gitHooks?.routerSettled(),
|
|
4064
4094
|
});
|
|
4065
4095
|
// The user answered an embedded ```ask picker: record the selections on the
|
|
4066
4096
|
// assistant message (locks the widget for every client, persists across
|
|
@@ -4239,6 +4269,7 @@ export function createAgentServer(opts) {
|
|
|
4239
4269
|
return handleAttachment(req, res, reqPath) || handlePlaytestFrame(req, res, reqPath);
|
|
4240
4270
|
}
|
|
4241
4271
|
function shutdown() {
|
|
4272
|
+
gitHooks?.stop();
|
|
4242
4273
|
taskStore.shutdown();
|
|
4243
4274
|
for (const child of [...taskChildren, ...routerChildren]) {
|
|
4244
4275
|
try {
|
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
import { type GitResult } from './gitRemote.js';
|
|
2
|
+
export type CommitReason = 'turn' | 'task' | 'leave' | 'manual' | 'sync';
|
|
3
|
+
export declare const COMMIT_REASONS: readonly CommitReason[];
|
|
4
|
+
export declare const AGENT_TRAILER_KEY = "Castle-Agent";
|
|
5
|
+
export declare const EXIT_OK = 0;
|
|
6
|
+
export declare const EXIT_ERROR = 1;
|
|
7
|
+
/** Not a sandbox, or a deck `git attach` never set up: nothing was done. */
|
|
8
|
+
export declare const EXIT_NOT_ENABLED = 2;
|
|
9
|
+
/** A merge with the remote is waiting on the agent; nothing was committed. */
|
|
10
|
+
export declare const EXIT_CONFLICT = 3;
|
|
11
|
+
export declare class CloudGitError extends Error {
|
|
12
|
+
readonly exitCode: number;
|
|
13
|
+
constructor(message: string, exitCode?: number);
|
|
14
|
+
}
|
|
15
|
+
export declare const CLOUD_EXCLUDES: string[];
|
|
16
|
+
export declare const LOOSE_OBJECT_LIMIT = 200;
|
|
17
|
+
export declare const STALE_GIT_LOCK_MS = 60000;
|
|
18
|
+
export declare const DECK_LOCK_FILE: string;
|
|
19
|
+
/** Written by `git sync` on a conflict; the serve turns it into an agent turn. */
|
|
20
|
+
export declare const CONFLICT_MARKER_FILE: string;
|
|
21
|
+
/** Written by `git attach` when it took the remote's version over a differing cloud copy. */
|
|
22
|
+
export declare const ADOPTED_MARKER_FILE: string;
|
|
23
|
+
/** Every marker the serve turns into an agent turn. */
|
|
24
|
+
export declare const AGENT_MARKER_FILES: readonly string[];
|
|
25
|
+
/** The serve's note that task agents (or the router) are working in the deck; see deckBusy. */
|
|
26
|
+
export declare const BUSY_FILE: string;
|
|
27
|
+
/** The remote has (or may have) work that waits to be merged until the deck is idle. */
|
|
28
|
+
export declare const SYNC_PENDING_FILE: string;
|
|
29
|
+
/** The conflicted merge in progress, in .git beside MERGE_HEAD. */
|
|
30
|
+
export declare const MERGE_STATE_FILE = "castle-merge.json";
|
|
31
|
+
/**
|
|
32
|
+
* Where `git attach` saves the cloud copy's files before taking the remote's version: one
|
|
33
|
+
* directory per attach. Under .git so no name a deck file may have (`*.pem`, `credentials`) is
|
|
34
|
+
* refused as a credential by the checkpoint, and never part of the working tree.
|
|
35
|
+
*/
|
|
36
|
+
export declare const ATTACH_BACKUPS_DIR: string;
|
|
37
|
+
/** Backups written by an attach whose agent notice has not been written yet. */
|
|
38
|
+
export declare const ADOPT_PENDING_FILE: string;
|
|
39
|
+
/** A leave commit found a merge waiting: the edits on disk stay uncommitted until it concludes. */
|
|
40
|
+
export declare const LEAVE_PENDING_FILE: string;
|
|
41
|
+
export declare const ATTACH_BACKUP_MAX_AGE_MS: number;
|
|
42
|
+
export declare const ATTACH_BACKUP_KEEP = 10;
|
|
43
|
+
export declare const DEADLINE_ENV = "CASTLE_GIT_DEADLINE";
|
|
44
|
+
export interface GitRunOptions {
|
|
45
|
+
timeoutMs?: number;
|
|
46
|
+
/** A scratch index instead of the repo's own. */
|
|
47
|
+
indexFile?: string;
|
|
48
|
+
}
|
|
49
|
+
export interface CloudGitDeps {
|
|
50
|
+
git: (args: string[], cwd: string, opts?: GitRunOptions) => GitResult;
|
|
51
|
+
/** The signed-in user, from the sandbox-scoped `me`. */
|
|
52
|
+
whoAmI: () => Promise<{
|
|
53
|
+
userId: string;
|
|
54
|
+
username: string;
|
|
55
|
+
} | null>;
|
|
56
|
+
env: NodeJS.ProcessEnv;
|
|
57
|
+
log: (message: string) => void;
|
|
58
|
+
warn: (message: string) => void;
|
|
59
|
+
now: () => number;
|
|
60
|
+
sleep: (ms: number) => void;
|
|
61
|
+
pid: number;
|
|
62
|
+
hostname: () => string;
|
|
63
|
+
isAlive: (pid: number) => boolean;
|
|
64
|
+
/** Whether this command has been asked to stop (SIGTERM). Lets pending signals in first. */
|
|
65
|
+
stopRequested: () => Promise<boolean>;
|
|
66
|
+
}
|
|
67
|
+
/** A process's start time (in clock ticks since boot, from /proc), which tells a reused pid apart. */
|
|
68
|
+
export declare function processStartTime(pid: number): string | null;
|
|
69
|
+
export declare function cloudGitRunner(baseEnv?: NodeJS.ProcessEnv): CloudGitDeps['git'];
|
|
70
|
+
export declare function defaultCloudGitDeps(whoAmI: CloudGitDeps['whoAmI']): CloudGitDeps;
|
|
71
|
+
interface Ctx {
|
|
72
|
+
dir: string;
|
|
73
|
+
deps: CloudGitDeps;
|
|
74
|
+
startedAt: number;
|
|
75
|
+
/** Epoch ms by which the command must be done (DEADLINE_ENV); none when not set. */
|
|
76
|
+
deadline?: number;
|
|
77
|
+
}
|
|
78
|
+
export declare function mergeInProgress(dir: string): boolean;
|
|
79
|
+
export declare function isSandboxEnv(env: NodeJS.ProcessEnv): boolean;
|
|
80
|
+
/** Whether `git attach` set this deck up: its own `.git` directory, marked in its config. */
|
|
81
|
+
export declare function isAttached(dir: string, git?: CloudGitDeps['git']): boolean;
|
|
82
|
+
/**
|
|
83
|
+
* The serve's switch: the gate env castle-www sets on the serve, AND a deck that attach
|
|
84
|
+
* actually set up. An attach that failed leaves the deck on the old version store.
|
|
85
|
+
*/
|
|
86
|
+
export declare function cloudGitMode(dir: string, env?: NodeJS.ProcessEnv): boolean;
|
|
87
|
+
/** cloudGitMode without blocking the caller's event loop. */
|
|
88
|
+
export declare function cloudGitModeAsync(dir: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
|
|
89
|
+
export declare function deckBusy(ctx: {
|
|
90
|
+
dir: string;
|
|
91
|
+
deps: Pick<CloudGitDeps, 'hostname' | 'isAlive'>;
|
|
92
|
+
}): boolean;
|
|
93
|
+
/** The serve's side of deckBusy. */
|
|
94
|
+
export declare function setDeckBusy(dir: string, busy: boolean): void;
|
|
95
|
+
/**
|
|
96
|
+
* An exclusive lock on `file`, returning its release. The lock is created exclusively (O_EXCL),
|
|
97
|
+
* names its holder (pid, container hostname, process start time) and a random token, and is
|
|
98
|
+
* released only by the holder whose token it still carries. A stale one is taken over through
|
|
99
|
+
* takeOverStaleLock. Until its content is written a lock reads as unreadable, which a waiter
|
|
100
|
+
* judges only by age -- a holder is not taken over in that instant.
|
|
101
|
+
*/
|
|
102
|
+
export declare function acquireLockFile(file: string, deps: CloudGitDeps, waitMs?: number): () => void;
|
|
103
|
+
export declare function clearStaleGitLocks(ctx: {
|
|
104
|
+
dir: string;
|
|
105
|
+
deps: Pick<CloudGitDeps, 'now' | 'warn'>;
|
|
106
|
+
}): string[];
|
|
107
|
+
export declare function noreplyEmail(userId: string, username: string): string;
|
|
108
|
+
/** A username as a git author name: no control characters or angle brackets, never empty. */
|
|
109
|
+
export declare function safeAuthorName(username: string): string;
|
|
110
|
+
/** How a conflicted path was left: markers for the agent, or the other computer's side taken. */
|
|
111
|
+
export type ConflictResolution = 'markers' | 'took-laptop' | 'laptop-deleted' | 'manual';
|
|
112
|
+
export interface ConflictedFile {
|
|
113
|
+
path: string;
|
|
114
|
+
/** Blob ids of the stages git left: base (1), this sandbox (2), the other computer (3). */
|
|
115
|
+
stages: {
|
|
116
|
+
base?: string;
|
|
117
|
+
ours?: string;
|
|
118
|
+
theirs?: string;
|
|
119
|
+
};
|
|
120
|
+
kind: 'text' | 'binary' | 'modify-delete';
|
|
121
|
+
resolution: ConflictResolution;
|
|
122
|
+
}
|
|
123
|
+
/** `.git/castle-merge.json`: the conflicted merge in progress. */
|
|
124
|
+
export interface MergeState {
|
|
125
|
+
at: string;
|
|
126
|
+
/** This sandbox's commit when the merge started. */
|
|
127
|
+
head: string;
|
|
128
|
+
mergeHead: string;
|
|
129
|
+
files: ConflictedFile[];
|
|
130
|
+
instruction: string;
|
|
131
|
+
}
|
|
132
|
+
export declare function readMergeState(dir: string): MergeState | null;
|
|
133
|
+
export interface ConflictReport {
|
|
134
|
+
at: string;
|
|
135
|
+
files: string[];
|
|
136
|
+
theirs: string[];
|
|
137
|
+
ours: string[];
|
|
138
|
+
instruction: string;
|
|
139
|
+
}
|
|
140
|
+
export interface ConflictSummary {
|
|
141
|
+
files: Pick<ConflictedFile, 'path' | 'resolution'>[];
|
|
142
|
+
theirs: string[];
|
|
143
|
+
ours: string[];
|
|
144
|
+
/** This sandbox's commit when the merge started, where its version of every file is. */
|
|
145
|
+
head: string;
|
|
146
|
+
}
|
|
147
|
+
export declare function conflictInstruction(summary: ConflictSummary): string;
|
|
148
|
+
export interface CommitOptions {
|
|
149
|
+
message?: string;
|
|
150
|
+
reason?: CommitReason;
|
|
151
|
+
paths?: string[];
|
|
152
|
+
/** Conclude the merge in progress (the only commit that may while one is). */
|
|
153
|
+
resolve?: boolean;
|
|
154
|
+
}
|
|
155
|
+
export interface CommitOutcome {
|
|
156
|
+
sha: string | null;
|
|
157
|
+
}
|
|
158
|
+
export declare function packIfNeeded(ctx: Ctx): boolean;
|
|
159
|
+
export interface LeavePending {
|
|
160
|
+
at: string;
|
|
161
|
+
/** What `git status` showed as changed when the user left. */
|
|
162
|
+
paths: string[];
|
|
163
|
+
}
|
|
164
|
+
export declare function readLeavePending(dir: string): LeavePending | null;
|
|
165
|
+
/**
|
|
166
|
+
* How a sync may touch the working tree: `full` fetches and merges castle/main into it;
|
|
167
|
+
* `push-only` (mid-task, or a commit of named paths) pushes main only as a fast-forward and
|
|
168
|
+
* otherwise leaves the remote's work for the board-idle commit to merge.
|
|
169
|
+
*/
|
|
170
|
+
export type SyncMode = 'full' | 'push-only';
|
|
171
|
+
export interface SyncOutcome {
|
|
172
|
+
/** What happened with castle/main. `deferred`: it has work that waits for the deck to be idle. */
|
|
173
|
+
merge: 'none' | 'fast-forward' | 'merged' | 'conflict' | 'seeded' | 'deferred';
|
|
174
|
+
pushed: boolean;
|
|
175
|
+
}
|
|
176
|
+
export interface DraftDifference {
|
|
177
|
+
path: string;
|
|
178
|
+
/** How the cloud copy differs from castle/main: `deleted` means it lacks a file the remote has. */
|
|
179
|
+
change: 'modified' | 'added' | 'deleted';
|
|
180
|
+
}
|
|
181
|
+
export declare function adoptedInstruction(backupDirs: string[]): string;
|
|
182
|
+
export interface AdoptOutcome {
|
|
183
|
+
/** Where the cloud copy's differing files were saved; null when it matched the remote. */
|
|
184
|
+
backup: string | null;
|
|
185
|
+
}
|
|
186
|
+
interface SyncAfter {
|
|
187
|
+
sync: SyncOutcome | null;
|
|
188
|
+
/** Set when the commit landed but the sync after it failed (the next one retries). */
|
|
189
|
+
syncError?: string;
|
|
190
|
+
}
|
|
191
|
+
export type CommitCommandOutcome = CommitOutcome & SyncAfter;
|
|
192
|
+
/**
|
|
193
|
+
* `castle-web commit`: commit, then sync. With named paths, or while the deck is busy, the
|
|
194
|
+
* sync only pushes (see SyncMode). The serve's commits skip the network when they committed
|
|
195
|
+
* nothing and there is nothing to push and no laptop push waiting.
|
|
196
|
+
*/
|
|
197
|
+
export declare function cloudCommit(dir: string, opts: CommitOptions, deps: CloudGitDeps): Promise<CommitCommandOutcome>;
|
|
198
|
+
/**
|
|
199
|
+
* `castle-web git sync`: commit work in progress, bring in castle/main, push. While the deck
|
|
200
|
+
* is busy it only notes that a sync is waiting: the board-idle commit does it.
|
|
201
|
+
*/
|
|
202
|
+
export declare function cloudSync(dir: string, deps: CloudGitDeps): Promise<SyncOutcome>;
|
|
203
|
+
export type RestoreOutcome = CommitOutcome & SyncAfter;
|
|
204
|
+
/**
|
|
205
|
+
* Restore the deck to an earlier commit as a NEW commit on top: history is never rewritten,
|
|
206
|
+
* so the restore can itself be restored away. Work in progress is committed first, so
|
|
207
|
+
* nothing on disk is lost by restoring.
|
|
208
|
+
*/
|
|
209
|
+
export declare function cloudRestore(dir: string, target: string, deps: CloudGitDeps): Promise<RestoreOutcome>;
|
|
210
|
+
export declare function writeCloudExcludes(dir: string): void;
|
|
211
|
+
export interface AttachOutcome {
|
|
212
|
+
repo: 'existing' | 'created';
|
|
213
|
+
outcome: 'seeded' | 'adopted' | 'synced';
|
|
214
|
+
sync?: SyncOutcome;
|
|
215
|
+
/** For `adopted`: where the cloud copy's differing files were saved, if any differed. */
|
|
216
|
+
backup?: string;
|
|
217
|
+
}
|
|
218
|
+
/** `castle-web git attach <dir> --remote <url>`. */
|
|
219
|
+
export declare function cloudAttach(dir: string, remoteUrl: string, deps: CloudGitDeps): Promise<AttachOutcome>;
|
|
220
|
+
export type GitChangeKind = 'added' | 'changed' | 'deleted';
|
|
221
|
+
export interface GitVersionEntry {
|
|
222
|
+
id: string;
|
|
223
|
+
parentId: string | null;
|
|
224
|
+
createdAt: string;
|
|
225
|
+
message: string;
|
|
226
|
+
author: string;
|
|
227
|
+
/** The Castle-Agent trailer's value when an agent made the commit. */
|
|
228
|
+
agent: string | null;
|
|
229
|
+
changes: {
|
|
230
|
+
path: string;
|
|
231
|
+
kind: GitChangeKind;
|
|
232
|
+
}[];
|
|
233
|
+
later: false;
|
|
234
|
+
}
|
|
235
|
+
export declare function parseGitLog(output: string): GitVersionEntry[];
|
|
236
|
+
export declare function parseStatus(output: string): {
|
|
237
|
+
path: string;
|
|
238
|
+
kind: GitChangeKind;
|
|
239
|
+
}[];
|
|
240
|
+
/**
|
|
241
|
+
* The Versions panel's picture with git on: the log and `git status` as pending. Async, since
|
|
242
|
+
* the IDE server's event loop must not wait on git, and without optional locks, so a panel
|
|
243
|
+
* refresh never holds the index lock a commit needs.
|
|
244
|
+
*/
|
|
245
|
+
export declare function gitVersionHistory(dir: string, env?: NodeJS.ProcessEnv): Promise<{
|
|
246
|
+
versions: GitVersionEntry[];
|
|
247
|
+
pending: {
|
|
248
|
+
path: string;
|
|
249
|
+
kind: GitChangeKind;
|
|
250
|
+
}[];
|
|
251
|
+
}>;
|
|
252
|
+
export declare function printGitLog(dir: string, from?: string, git?: CloudGitDeps['git']): void;
|
|
253
|
+
export declare function printGitShow(dir: string, target: string, git?: CloudGitDeps['git']): void;
|
|
254
|
+
export {};
|