kcode-web-libs 0.1.0

Managed plain HTML, CSS, and JavaScript libraries with browser checks and immutable publication
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

# API

```rust
pub struct File {
    pub path: String,
    pub contents: String,
}

pub struct Lib {
    pub files: Vec<File>,
    // private fields
}

pub fn create(
    web_libs_root: impl AsRef<Path>,
    name: &str,
) -> Result<Lib>;
pub fn open(
    web_libs_root: impl AsRef<Path>,
    name: &str,
) -> Result<Lib>;
pub fn docs(
    web_libs_root: impl AsRef<Path>,
    name: &str,
) -> Result<(String, String)>;

impl Lib {
    pub fn write(&mut self) -> Result<()>;
    pub fn check(&self) -> Result<()>;
    pub fn publish(&self) -> Result<()>;
}
```

- `create` creates a minimal buildless ES module at version `0.1.0`.
- `open` returns the complete canonically sorted UTF-8 source.
- `docs` returns the manifest version and root `Documentation.md`.
- `write` commits `files` as the complete replacement. Omitted files are
  deleted. Reopen after a `stale_snapshot` error.
- `check` validates exactly the current in-memory source in headless Chromium.
- `publish` rechecks and publishes exactly the current in-memory source.

Every source contains `Documentation.md` and `kcode-web.json`:

```json
{
  "name": "example",
  "version": "0.1.0",
  "entry": "index.js",
  "tests": "tests.js"
}
```

The manifest name matches the managed library. Its version is a literal
canonical stable `major.minor.patch`, and both module paths identify retained
`.js` or `.mjs` files.

`check` materializes a disposable copy, serves it and already-published exact
version dependencies on loopback, imports the entry, imports the test module,
and awaits its exported `runTests()` function. It starts `chromium` through
`PATH`. The module owns assertions, setup, and test-mode API substitutes.

`publish` performs that complete check first. It then writes and synchronizes an
independent complete copy at
`<web_libs_root>/.published/module/<name>/v<version>/`. Existing name/version
pairs are rejected and files are not deduplicated between versions. Trusted
coordinator assets live under `<web_libs_root>/.coordinator/`; source
repositories live directly under `<web_libs_root>/<name>/`.

Source writes synchronize every staged file and directory, install and
synchronize the complete generation, then atomically replace synchronized
`HEAD` and synchronize the repository directory. A `source_commit_uncertain`
error means `HEAD` was replaced but its final directory synchronization failed;
reopen before further action. A `source_generation_commit_uncertain` error
means the new generation was installed but `HEAD` was not changed.

A `publish.commit_uncertain` error means the complete version destination
was installed but its final parent-directory synchronization failed. Inspect
that exact destination before retrying.

The caller owns the managed root, installation of `chromium` on `PATH`,
transport, authorization, model-facing schemas, production HTTP routing,
floating aliases, application selection, deployment, and rollback.