Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 13 additions & 17 deletions .agents/skills/layerfs-js-sdk/references/methods/branch.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,14 +125,10 @@ reply, never out of the merge. For an incomplete summary, page

## `branch.publish`

`branch.publish(project, branch, commit?, { expected_base, expected_head, force })`
`branch.publish(project, branch, commit?)`

Makes `main` show the Branch's head, or the given Commit, by adding a Layer
to `main`. It refuses (`HeadMoved`) when `main` gained a Layer since your
Branch forked, so another agent's work is never dropped by accident.
`expected_base` (a Layer id) and `expected_head` (a Commit id) refuse unless
`main` and your Branch are still where you read them; `force: true`
overwrites `main` on purpose.
to `main`.

```bash
layerfs branch publish shop/api work
Expand All @@ -147,29 +143,29 @@ layerfs branch publish shop/api work

| `kind` | Meaning |
| --- | --- |
| `Added` | `main` now shows that Commit; `published_layer` is the new Layer; `overwrote` lists `main` Layers that a `force` publish skipped |
| `UpToDate` | That Commit is already published (`{ kind, layer }`), even if `main` moved on since |
| `NoChanges` | `main` already holds that tree (`{ kind, head_layer }`) |
| `Added` | `main` now shows that Commit; `published_layer` is the new Layer; `overwrote` lists `main` Layers that were skipped |
| `UpToDate` | `main` already shows it (`{ kind, layer }`) |
| `NoChanges` | Nothing to publish (1.1.0 shape; not seen in this pass) |

| Code | Meaning | Do |
| --- | --- | --- |
| `NoCommit` | The Branch has no Commit yet | Commit something first |
| `NoSuchBranch` | No such Branch | Check the name |
| `HeadMoved` | `main` moved since your Branch forked (or since `expected_base`), or the Branch head is not `expected_head`; `detail` has `expectedBase`/`actualBase` or `expectedHead`/`actualHead` | Merge with `main` into a new Branch (below), then publish that |
| `InvalidInput` | `commit` is not a full Commit id, or an expected id names the wrong kind | Pass a full id |
| `HeadMoved` | `main` moved during the call | Merge `main` in (below), then publish again |
| `InvalidInput` | `commit` is not a full Commit id | Pass a full id |

**Publishing replaces `main`'s view** with your Commit, so it is refused when
`main` has Layers your Commit doesn't contain. Publishing your own Branch
again at milestones is fine. If someone else published since you forked,
merge `main` in (a merge makes a new Branch), check the result, then publish
the merged Branch:
**Publishing replaces `main`'s view** with your Commit. Layers published to
`main` after your Branch's base that your Commit doesn't contain are skipped:
they stay in history and `overwrote` lists them. If someone else may have
published since you forked, merge `main` in first, check the result, then
publish the merged Branch:

```js
const P = "shop/api";
const m = await layerfs.branch.merge(P, "work-release", "work", "main", { message: "merge main before publish" });
// mount m.branch in a Sandbox and run the tests here, then:
const p = await layerfs.branch.publish(P, m.branch);
// a merge with main publishes as a fast-forward: nothing is skipped
if (p.kind === "Added" && p.overwrote.length) console.log("warning: skipped", p.overwrote);
```

## `branch.diff`
Expand Down
862 changes: 480 additions & 382 deletions AGENTS.md

Large diffs are not rendered by default.

17 changes: 8 additions & 9 deletions api/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,7 @@ public surface:
`node/layerfs.node` by `scripts/build-native.mjs`; the package loads that
file or the one `LAYERFS_NATIVE` names, nothing else.
- `crates/layerfs-python`: the PyO3 module `layerfs._native`.
- `node/`: the SDK for Node, `@layerfs/node`.
- `cli/`: the `layerfs` command's package, `@layerfs/cli`.
- `mcp/`: the MCP server over stdio, `@layerfs/mcp` (private).
- `node/`: the one published JavaScript package, `layerfs`.
- `python/`: the Python package `layerfs`.

The packages are thin shells over the table: each function is one library
Expand All @@ -43,17 +41,18 @@ ordinary daemon binary before running tests that launch it.
`LAYERFS_TEST_DAEMON` may select an explicit binary; otherwise the tests
locate the sibling Cargo output. The owner keeps `layerfs-node` out of CI.

API code follows the engine guide's
All API product code follows the
[production size and responsibility rules](../engine/AGENTS.md#production-file-size-and-responsibility)
and [checks](../engine/AGENTS.md#checks-and-completion), and the root guide's
[rules you must not break](../AGENTS.md#rules-you-must-not-break). Preserve the
existing unsafe-code boundaries; do not add test hooks or inline tests to
production src.
and [checks and completion rules](../engine/AGENTS.md#checks-and-completion),
including bounded test commands, build-before-run, locked dependencies, ARM64
flags, per-commit LOC and the Disposable-only profile. Preserve the existing
unsafe-code boundaries; do not add test hooks or inline tests to production src.
Do not add a call, argument or result name in JavaScript: change the call's
entry in `crates/layerfs-api/src/<family>/<call>.rs` and the package follows.
`layerfs-api/src` holds only `lib.rs`, the call machinery `calls/` (table
shape, checks, scope, keys, dispatcher, `Context`; layerfs-project#107) and
one folder per family: its `mod.rs` (the family's calls in help order) and
one file per call (its table entry and the function that runs it: one call
of a control crate's per-op function, never an op name as a string). A
test pins this shape (`tests/calls_table.rs`).
test pins this shape (`tests/calls_table.rs`). CI reports and does not gate a
push.
13 changes: 3 additions & 10 deletions api/crates/layerfs-api/src/branch/publish.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
//! `branch.publish`: a Branch's head or Commit as main's next Layer.
use crate::calls::table::Kind::{Bool, Name, Project};
use crate::calls::table::Kind::{Name, Project};
use crate::calls::table::{a, call, opt, Call};
use crate::calls::Context;
use layerfs_bridge::control::SdkValue;
Expand All @@ -15,12 +15,8 @@ pub(crate) const CALL: Call = call(
a("branch", Name),
opt("commit", Name),
],
&[
opt("expected_base", Name),
opt("expected_head", Name),
opt("force", Bool),
],
"a Branch's head or Commit as main's next Layer, refusing a stale base",
&[],
"a Branch's head or Commit as main's next Layer",
run,
);

Expand All @@ -31,9 +27,6 @@ fn run(context: &mut Context<'_>, args: &SdkValue) -> Outcome {
project: text("project").unwrap_or_default(),
branch: text("branch").unwrap_or_default(),
commit: text("commit"),
expected_base: text("expected_base"),
expected_head: text("expected_head"),
force: args.get("force").map(|_| args.get_bool("force")),
};
let (home, events) = context.parts();
publish(home, events, &request)
Expand Down
91 changes: 0 additions & 91 deletions api/crates/layerfs-api/tests/calls_table.rs
Original file line number Diff line number Diff line change
Expand Up @@ -139,97 +139,6 @@ fn branch_family() {
assert!(!reached.starts_with("InvalidInput"), "{reached}");
}

#[test]
fn branch_publish_declares_its_expected_base_options() {
// The shell, Node and Python front ends build their arguments from this
// table, so these options (and their shapes) are the CLI's and SDK's.
let call = layerfs_api::calls()
.into_iter()
.find(|call| call.family == "branch" && call.call == "publish")
.expect("branch.publish is in the table");
let declared: Vec<(&str, Kind, bool)> = call
.options
.iter()
.map(|option| (option.name, option.kind, option.optional))
.collect();
assert_eq!(
declared,
vec![
("expected_base", Kind::Name, true),
("expected_head", Kind::Name, true),
("force", Kind::Bool, true),
]
);
assert_eq!(
call.help,
"a Branch's head or Commit as main's next Layer, refusing a stale base"
);
}

#[test]
fn branch_publish_expectations_are_plumbed() {
for (name, value, why) in [
(
"expected_base",
SdkValue::Int(1),
"`expected_base` must be text",
),
(
"expected_base",
SdkValue::Bool(true),
"`expected_base` must be text",
),
(
"expected_head",
SdkValue::Bool(true),
"`expected_head` must be text",
),
(
"expected_head",
SdkValue::Int(1),
"`expected_head` must be text",
),
("force", t("yes"), "`force` must be true or false"),
("force", SdkValue::Int(1), "`force` must be true or false"),
] {
let refused = code(
"branch.publish",
map(&[
("project", t("shop/api")),
("branch", t("work")),
(name, value),
]),
);
assert!(refused.contains(why), "{name}: {refused}");
}
// A misspelled option is not read as an argument of the call.
let typo = code(
"branch.publish",
map(&[
("project", t("shop/api")),
("branch", t("work")),
("expectedBase", t("00")),
]),
);
assert!(
typo.starts_with("InvalidInput: branch.publish: unknown argument `expectedBase`"),
"{typo}"
);
// A well-shaped expectation reaches the call instead of being refused by
// argument checking.
let reached = code(
"branch.publish",
map(&[
("project", t("shop/api")),
("branch", t("work")),
("expected_base", t("00")),
("expected_head", t("00")),
("force", SdkValue::Bool(true)),
]),
);
assert!(!reached.starts_with("InvalidInput"), "{reached}");
}

#[test]
fn commit_family() {
assert!(code(
Expand Down
105 changes: 0 additions & 105 deletions api/crates/layerfs-cli/tests/publish_options.rs

This file was deleted.

20 changes: 4 additions & 16 deletions api/node/src/index.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -131,13 +131,6 @@ export interface BranchMergeOptions extends CallOptions {
units?: Value;
}

/** Options of `branch.publish`; an unknown option is refused. */
export interface BranchPublishOptions extends CallOptions {
expected_base?: string;
expected_head?: string;
force?: boolean;
}

/** Options of `branch.diff`; an unknown option is refused. */
export interface BranchDiffOptions extends CallOptions {
paths_only?: boolean;
Expand Down Expand Up @@ -327,11 +320,6 @@ export interface MachineStartOptions extends CallOptions {
on_progress?: ProgressHandler;
}

/** Options of `machine.stop`; an unknown option is refused. */
export interface MachineStopOptions extends CallOptions {
force?: boolean;
}

/** Options of `machine.create`; an unknown option is refused. */
export interface MachineCreateOptions extends CallOptions {
cpus?: WholeNumber;
Expand Down Expand Up @@ -435,9 +423,9 @@ export interface BranchFamily {
fork(project: string, name: string, from_branch: string, from_commit?: string | null, options?: CallOptions): Promise<Result>;
/** merge two Branches into a new one */
merge(project: string, name: string, a: string, b: string, options?: BranchMergeOptions): Promise<Result>;
/** a Branch's head or Commit as main's next Layer, refusing a stale base */
publish(project: string, branch: string, options: BranchPublishOptions): Promise<Result>;
publish(project: string, branch: string, commit?: string | null, options?: BranchPublishOptions): Promise<Result>;
/** a Branch's head or Commit as main's next Layer */
publish(project: string, branch: string, options: CallOptions): Promise<Result>;
publish(project: string, branch: string, commit?: string | null, options?: CallOptions): Promise<Result>;
/** files that differ between two Branches' heads */
diff(project: string, from_branch: string, to_branch: string, options?: BranchDiffOptions): Promise<Result>;
}
Expand Down Expand Up @@ -537,7 +525,7 @@ export interface MachineFamily {
/** start a stopped machine and its worker; a running one answers at once */
start(name: string, options?: MachineStartOptions): Promise<Result>;
/** stop a machine's worker and VM; its disks stay */
stop(name: string, options?: MachineStopOptions): Promise<Result>;
stop(name: string, options?: CallOptions): Promise<Result>;
/** create an enabled VM machine (apple-container, lima) */
create(name: string, platform: string, options?: MachineCreateOptions): Promise<Result>;
/** delete a VM machine and its disk; one of a removed platform is only forgotten */
Expand Down
Loading