@plannotator/tot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plannotator
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+<p align="center">
+  <img src="./site/assets/readme/totpage2.webp" alt="tot" width="700">
+  <br>
+  <sub><a href="https://tot.page">tot.page</a> is what enables <a href="https://plannotator.ai/workspaces">Plannotator Workspaces</a></sub>
+</p>
+
+# tot.page
+
+Publish a markdown or HTML file to a live link in one command. No signup.
+
+```bash
+npm i -g @plannotator/tot
+```
+
+```
+tot notes.md
+  ↳ https://tot.page/aB3xK9q
+  commit  e5f6c1a
+  frozen  https://tot.page/aB3xK9q/index.md@e5f6c1a
+```
+
+## Commands
+
+| Command                 | What it does                                                                           |
+| ----------------------- | -------------------------------------------------------------------------------------- |
+| `tot notes.md`          | Publish markdown as the raw `.md` file.                                                |
+| `tot page.html`         | Publish HTML as the raw `.html` file, plus local support files it directly references. |
+| `tot update <link>`     | Push new content. The same link updates.                                               |
+| `tot list`              | Show what you have published.                                                          |
+| `tot remove <link>`     | Remove the living page from its share link.                                            |
+| `tot login --key <key>` | Optional. Publish as an owned account instead of anonymous.                            |
+
+## How it works
+
+Files are served byte for byte. Markdown comes back as raw markdown. HTML comes back as raw HTML.
+
+For HTML, `tot` also uploads direct local browser dependencies before the page goes live: images,
+stylesheets, scripts, video, `srcset` entries, and video posters. It skips external URLs and ordinary
+navigation links. There is no config file, build step, routing layer, or bundler.
+
+Your link is live. Run `tot update` and the same `tot.page/...` link shows the new version. Every version also keeps a frozen `@hash` link that never changes, for when you want a fixed snapshot.
+
+`tot remove` removes the living page. Frozen snapshot links are permanent while the workspace exists.
+
+No accounts, no tokens. The link is the key.
+
+> A page you publish is open. Anyone who has the link can view it, update it, or delete it. There is no private mode. Share the link with that in mind.
+
+## Configuration
+
+State lives in `~/.tot`: the API endpoint and the list of pages you have published. Override the API origin for one run with `--endpoint <url>`.
+
+## Built on
+
+[Cloudflare Artifacts](https://www.cloudflare.com/products/artifacts/). Every version is a real git commit.
+
+## License
+
+MIT

package/dist/asset-refs.d.ts

@@ -0,0 +1,16 @@
+export type AssetContentType = "image/png" | "image/jpeg" | "image/gif" | "image/webp" | "image/svg+xml" | "text/css" | "application/javascript" | "video/mp4";
+export interface HtmlAssetRef {
+    /** The literal URL-like value from the HTML, before query/hash stripping. */
+    ref: string;
+    /** Workspace asset path to upload, relative to the HTML file's folder. */
+    assetPath: string;
+    /** Absolute local file path to read. */
+    localPath: string;
+    contentType: AssetContentType;
+}
+export declare const MAX_ASSET_BYTES: number;
+export declare const MAX_ASSET_BYTES_LABEL = "10 MiB";
+export declare function contentTypeForAssetPath(assetPath: string): AssetContentType | null;
+export declare function validWorkspacePath(value: string): boolean;
+export declare function encodeWorkspacePath(value: string): string;
+export declare function collectHtmlAssetRefs(html: string, htmlFilePath: string): HtmlAssetRef[];

package/dist/asset-refs.js

@@ -0,0 +1,204 @@
+import path from "node:path";
+import * as parse5 from "parse5";
+export const MAX_ASSET_BYTES = 10 * 1024 * 1024;
+export const MAX_ASSET_BYTES_LABEL = "10 MiB";
+const CONTENT_TYPES_BY_EXT = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".css": "text/css",
+    ".js": "application/javascript",
+    ".mjs": "application/javascript",
+    ".mp4": "video/mp4",
+};
+export function contentTypeForAssetPath(assetPath) {
+    return CONTENT_TYPES_BY_EXT[path.extname(assetPath).toLowerCase()] ?? null;
+}
+export function validWorkspacePath(value) {
+    if (value.length === 0)
+        return false;
+    if (value.startsWith("/") || value.endsWith("/") || value.includes("//"))
+        return false;
+    if (/[\\?#%]/u.test(value))
+        return false;
+    for (let i = 0; i < value.length; i++) {
+        if (value.charCodeAt(i) < 0x20)
+            return false;
+    }
+    for (const segment of value.split("/")) {
+        if (segment === "." || segment === "..")
+            return false;
+    }
+    return true;
+}
+export function encodeWorkspacePath(value) {
+    return value.split("/").map(encodeURIComponent).join("/");
+}
+export function collectHtmlAssetRefs(html, htmlFilePath) {
+    const root = parse5.parse(html);
+    const baseDir = path.dirname(path.resolve(htmlFilePath));
+    const refs = [];
+    visit(root, refs);
+    const seen = new Set();
+    const assets = [];
+    for (const ref of refs) {
+        const resolved = resolveLocalAssetRef(ref, baseDir);
+        if (resolved === null)
+            continue;
+        if (seen.has(resolved.assetPath))
+            continue;
+        seen.add(resolved.assetPath);
+        assets.push(resolved);
+    }
+    return assets;
+}
+function visit(node, refs) {
+    const tagName = node.tagName?.toLowerCase();
+    if (tagName !== undefined)
+        collectRefsForNode(tagName, node, refs);
+    for (const child of node.childNodes ?? [])
+        visit(child, refs);
+}
+function collectRefsForNode(tagName, node, refs) {
+    if (tagName === "base" && attr(node, "href") !== null) {
+        throw new Error("unsupported <base href>: tot resolves support files relative to the HTML file");
+    }
+    if (tagName === "img") {
+        pushAttr(node, "src", refs);
+        pushSrcset(node, refs);
+        return;
+    }
+    if (tagName === "source") {
+        pushAttr(node, "src", refs);
+        pushSrcset(node, refs);
+        return;
+    }
+    if (tagName === "video") {
+        pushAttr(node, "src", refs);
+        pushAttr(node, "poster", refs);
+        return;
+    }
+    if (tagName === "script") {
+        pushAttr(node, "src", refs);
+        return;
+    }
+    if (tagName === "link" && isSupportLink(node)) {
+        pushAttr(node, "href", refs);
+    }
+}
+function pushAttr(node, name, refs) {
+    const value = attr(node, name);
+    if (value !== null)
+        refs.push(value);
+}
+function pushSrcset(node, refs) {
+    const value = attr(node, "srcset");
+    if (value === null)
+        return;
+    for (const candidate of parseSrcsetUrls(value))
+        refs.push(candidate);
+}
+function attr(node, name) {
+    const target = name.toLowerCase();
+    for (const a of node.attrs ?? []) {
+        if (a.name.toLowerCase() === target)
+            return a.value.trim();
+    }
+    return null;
+}
+function isSupportLink(node) {
+    const rel = attr(node, "rel");
+    if (rel === null)
+        return false;
+    const tokens = new Set(rel.toLowerCase().split(/\s+/).filter(Boolean));
+    return (tokens.has("stylesheet") ||
+        tokens.has("preload") ||
+        tokens.has("modulepreload") ||
+        tokens.has("icon") ||
+        tokens.has("apple-touch-icon") ||
+        tokens.has("mask-icon"));
+}
+function parseSrcsetUrls(srcset) {
+    const urls = [];
+    let i = 0;
+    while (i < srcset.length) {
+        while (i < srcset.length && /[\s,]/u.test(srcset[i]))
+            i++;
+        const start = i;
+        while (i < srcset.length && !/\s/u.test(srcset[i]) && srcset[i] !== ",")
+            i++;
+        // data: URLs can contain commas; keep reading until the descriptor
+        // whitespace. The URL-level scheme skip will discard it later.
+        if (srcset.slice(start, i).toLowerCase().startsWith("data:")) {
+            while (i < srcset.length && !/\s/u.test(srcset[i]))
+                i++;
+        }
+        const url = srcset.slice(start, i);
+        if (url !== "")
+            urls.push(url);
+        while (i < srcset.length && srcset[i] !== ",")
+            i++;
+    }
+    return urls;
+}
+function resolveLocalAssetRef(ref, baseDir) {
+    const stripped = stripQueryAndHash(ref.trim());
+    if (stripped === null)
+        return null;
+    const decoded = decodePath(stripped);
+    const normalized = decoded.replace(/\\/g, "/");
+    const skip = skipReason(normalized);
+    if (skip === "external")
+        return null;
+    if (skip === "root-relative") {
+        throw new Error(`root-relative asset ref is unsupported: ${ref} (use a relative path)`);
+    }
+    const assetPath = path.posix.normalize(normalized);
+    if (!validWorkspacePath(assetPath)) {
+        throw new Error(`unsupported local asset ref: ${ref}`);
+    }
+    const contentType = contentTypeForAssetPath(assetPath);
+    if (contentType === null) {
+        throw new Error(`unsupported asset type for local ref: ${ref}`);
+    }
+    return {
+        ref,
+        assetPath,
+        localPath: path.resolve(baseDir, assetPath),
+        contentType,
+    };
+}
+function stripQueryAndHash(ref) {
+    if (ref === "" || ref.startsWith("#"))
+        return null;
+    const splitAt = firstIndexOf(ref, ["?", "#"]);
+    return splitAt < 0 ? ref : ref.slice(0, splitAt);
+}
+function firstIndexOf(value, needles) {
+    let idx = -1;
+    for (const needle of needles) {
+        const found = value.indexOf(needle);
+        if (found >= 0 && (idx < 0 || found < idx))
+            idx = found;
+    }
+    return idx;
+}
+function decodePath(ref) {
+    try {
+        return decodeURIComponent(ref);
+    }
+    catch {
+        throw new Error(`invalid percent-encoding in local asset ref: ${ref}`);
+    }
+}
+function skipReason(ref) {
+    if (ref === "" || ref.startsWith("//"))
+        return "external";
+    if (ref.startsWith("/"))
+        return "root-relative";
+    const schemeMatch = /^[a-z][a-z0-9+.-]*:/i.exec(ref);
+    return schemeMatch !== null ? "external" : null;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { listCommand, loginCommand, publishCommand, removeCommand, updateCommand, } from "./commands.js";
+import { Config } from "./config.js";
+import { createHttpClient } from "./http.js";
+function parseArgs(argv) {
+    const out = { _: [], flags: {} };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith("--")) {
+            const key = a.slice(2);
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("--")) {
+                out.flags[key] = true;
+            }
+            else {
+                out.flags[key] = next;
+                i++;
+            }
+        }
+        else {
+            out._.push(a);
+        }
+    }
+    return out;
+}
+function flagStr(flags, name) {
+    const v = flags[name];
+    return typeof v === "string" ? v : undefined;
+}
+const HELP = `tot — publish a page to tot.page
+
+  tot <file>              publish a raw markdown or html file
+  tot update <file|url>   push new content to the same living URL
+  tot remove <file|url>   delete a page (anyone with the link can; so can you)
+  tot list                list pages you've published from this machine
+  tot login --key <KEY>   save a pre-minted wsk_live_ key to ~/.tot (optional)
+
+flags
+  --endpoint <url>   override the API origin (default https://api.tot.page)
+  --key <KEY>        API key for this run (login persists it)
+  --help             show this help`;
+function makeDeps(cfg) {
+    return {
+        http: createHttpClient(cfg),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        now: () => Date.now(),
+        log: (msg) => console.log(msg),
+    };
+}
+export async function main(argv = process.argv.slice(2)) {
+    const args = parseArgs(argv);
+    const cfg = Config.load();
+    if (flagStr(args.flags, "endpoint")) {
+        cfg.endpoint = flagStr(args.flags, "endpoint");
+    }
+    if (flagStr(args.flags, "key")) {
+        cfg.key = flagStr(args.flags, "key");
+    }
+    const cmd = args._[0];
+    if (!cmd || cmd === "help" || args.flags.help === true) {
+        console.log(HELP);
+        return 0;
+    }
+    const deps = makeDeps(cfg);
+    if (cmd === "login") {
+        const key = flagStr(args.flags, "key") ?? cfg.key ?? undefined;
+        if (!key) {
+            console.error("provide a key:  tot login --key <KEY>");
+            return 1;
+        }
+        await loginCommand(key, cfg, deps);
+        return 0;
+    }
+    if (cmd === "list") {
+        listCommand(cfg, deps);
+        return 0;
+    }
+    if (cmd === "update") {
+        const target = args._[1];
+        if (!target) {
+            console.error("usage: tot update <file|url>");
+            return 1;
+        }
+        await updateCommand(target, cfg, deps);
+        return 0;
+    }
+    if (cmd === "remove" || cmd === "rm" || cmd === "delete") {
+        const target = args._[1];
+        if (!target) {
+            console.error("usage: tot remove <file|url>");
+            return 1;
+        }
+        await removeCommand(target, cfg, deps);
+        return 0;
+    }
+    // Default: the first positional is a file to publish.
+    await publishCommand(cmd, cfg, deps);
+    return 0;
+}
+// Only run when invoked as the CLI, not when imported (e.g. by tests).
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main().then((code) => process.exit(code), (err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error("error:", msg);
+        process.exit(1);
+    });
+}

package/dist/commands.d.ts

@@ -0,0 +1,42 @@
+import type { Config } from "./config.js";
+import { type HttpClient } from "./http.js";
+/** Injected side-effects, so commands stay testable (no real clock, no console). */
+export interface CommandDeps {
+    http: HttpClient;
+    /** Resolves after `ms` — overridable in tests to make polling instant. */
+    sleep: (ms: number) => Promise<void>;
+    /** Monotonic clock in ms — overridable in tests to drive the timeout. */
+    now: () => number;
+    log: (msg: string) => void;
+}
+export declare const POLL_INTERVAL_MS = 500;
+export declare const POLL_TIMEOUT_MS = 30000;
+export interface PublishOpts {
+    /** Override the detected kind (rarely needed; extension wins by default). */
+    kind?: "markdown" | "html";
+}
+/**
+ * Build the living URL. `index.md`/`index.html` resolve to the bare workspace
+ * (mirrors `/s/{slug}`); anything else appends the doc path.
+ */
+export declare function livingUrl(contentOrigin: string, slug: string, docPath: string): string;
+/** Build the immutable, commit-pinned URL for one exact file version. */
+export declare function frozenUrl(contentOrigin: string, slug: string, docPath: string, version: string): string;
+/**
+ * `tot <file>` — publish a new page.
+ * POST /v1/documents → poll GET until `version` is non-null → print living URL.
+ */
+export declare function publishCommand(file: string, cfg: Config, deps: CommandDeps, opts?: PublishOpts): Promise<void>;
+/**
+ * `tot update <file|url>` — push new content under the same living URL.
+ * Resolves {wsId, docId} from the local registry, then PUTs the raw body.
+ */
+export declare function updateCommand(target: string, cfg: Config, deps: CommandDeps): Promise<void>;
+/**
+ * `tot remove <file|url|slug>` — hard-delete the page and prune the registry.
+ */
+export declare function removeCommand(target: string, cfg: Config, deps: CommandDeps): Promise<void>;
+/** `tot list` — purely local; print the pages published from this machine. */
+export declare function listCommand(cfg: Config, deps: CommandDeps): void;
+/** `tot login --key <KEY>` — store a pre-minted key and verify it via /v1/me. */
+export declare function loginCommand(key: string, cfg: Config, deps: CommandDeps): Promise<void>;

package/dist/commands.js

@@ -0,0 +1,250 @@
+import fs from "node:fs";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { collectHtmlAssetRefs, encodeWorkspacePath, MAX_ASSET_BYTES, MAX_ASSET_BYTES_LABEL, validWorkspacePath, } from "./asset-refs.js";
+import { deleteDocument, getDocument, getMe, postDocument, postWorkspace, postWorkspaceDocument, putAsset, putDocument, } from "./http.js";
+export const POLL_INTERVAL_MS = 500;
+export const POLL_TIMEOUT_MS = 30_000;
+function detectKind(file) {
+    const ext = path.extname(file).toLowerCase();
+    if (ext === ".html" || ext === ".htm")
+        return "html";
+    return "markdown";
+}
+function contentTypeFor(kind) {
+    return kind === "html" ? "text/html" : "text/markdown";
+}
+/**
+ * Build the living URL. `index.md`/`index.html` resolve to the bare workspace
+ * (mirrors `/s/{slug}`); anything else appends the doc path.
+ */
+export function livingUrl(contentOrigin, slug, docPath) {
+    const base = contentOrigin.replace(/\/+$/, "");
+    if (docPath === "index.md" || docPath === "index.html") {
+        return `${base}/${slug}`;
+    }
+    return `${base}/${slug}/${encodeWorkspacePath(docPath)}`;
+}
+/** Build the immutable, commit-pinned URL for one exact file version. */
+export function frozenUrl(contentOrigin, slug, docPath, version) {
+    const base = contentOrigin.replace(/\/+$/, "");
+    return `${base}/${slug}/${encodeWorkspacePath(docPath)}@${version}`;
+}
+function shortCommit(version) {
+    return version.slice(0, 7);
+}
+/**
+ * `tot <file>` — publish a new page.
+ * POST /v1/documents → poll GET until `version` is non-null → print living URL.
+ */
+export async function publishCommand(file, cfg, deps, opts = {}) {
+    // Catches the no-network-on-missing-file contract: this throws before any
+    // HTTP call, so a typo never hits the server.
+    if (!fs.existsSync(file)) {
+        throw new Error(`file not found: ${file}`);
+    }
+    const body = fs.readFileSync(file, "utf8");
+    const kind = opts.kind ?? detectKind(file);
+    const assetRefs = collectAssetsForPublish(kind, body, file);
+    const targetDocPath = assetRefs.length > 0 ? publishDocPath(file) : null;
+    const assets = prepareAssetRefs(assetRefs);
+    let wsId;
+    let docId;
+    let slug;
+    let docPath;
+    let version;
+    let fileUrl;
+    if (assetRefs.length === 0) {
+        const created = await postDocument(deps.http, kind, body);
+        wsId = created.workspace.id;
+        docId = created.document.id;
+        slug = created.workspace.slug;
+        docPath = created.document.doc_path;
+        version = created.document.version;
+        fileUrl = created.document.file_url ?? null;
+    }
+    else {
+        if (targetDocPath === null) {
+            throw new Error("internal error: missing target document path for HTML assets publish");
+        }
+        const workspace = await postWorkspace(deps.http);
+        wsId = workspace.id;
+        slug = workspace.slug;
+        await uploadAssetRefs(deps.http, wsId, assets);
+        const document = await postWorkspaceDocument(deps.http, wsId, targetDocPath, kind, body);
+        docId = document.id;
+        docPath = document.doc_path;
+        version = document.version;
+        fileUrl = document.file_url ?? null;
+    }
+    // Poll until the first save lands (version flips from null). Bounded by a
+    // 30s timeout so a stuck publish fails loudly instead of hanging forever.
+    const start = deps.now();
+    // Sequential by design: each poll waits for the previous to settle (the loop
+    // IS the wait), so the await-in-loop warning doesn't apply here.
+    // oxlint-disable no-await-in-loop
+    while (version === null) {
+        if (deps.now() - start > POLL_TIMEOUT_MS) {
+            throw new Error("document failed to publish; version is still null after 30s");
+        }
+        await deps.sleep(POLL_INTERVAL_MS);
+        const doc = await getDocument(deps.http, wsId, docId);
+        version = doc.version;
+        docPath = doc.doc_path;
+        fileUrl = doc.file_url ?? fileUrl;
+    }
+    // oxlint-enable no-await-in-loop
+    const url = livingUrl(cfg.contentOrigin, slug, docPath);
+    const snapshotUrl = fileUrl ?? frozenUrl(cfg.contentOrigin, slug, docPath, version);
+    const entry = {
+        wsId,
+        docId,
+        slug,
+        url,
+        kind,
+        docPath,
+        bytes: Buffer.byteLength(body, "utf8"),
+        assets: registryAssets(assets),
+        createdAt: new Date().toISOString(),
+    };
+    cfg.addEntry(file, entry);
+    cfg.save();
+    deps.log("");
+    deps.log(`  ↳ ${url}`);
+    deps.log(`  commit  ${shortCommit(version)}`);
+    deps.log(`  frozen  ${snapshotUrl}`);
+    deps.log("");
+}
+/**
+ * `tot update <file|url>` — push new content under the same living URL.
+ * Resolves {wsId, docId} from the local registry, then PUTs the raw body.
+ */
+export async function updateCommand(target, cfg, deps) {
+    const resolved = cfg.resolve(target);
+    if (!resolved) {
+        throw new Error(`not in your registry: ${target} (publish it first, or run 'tot list')`);
+    }
+    const { entry } = resolved;
+    // Update always reads new content from a LOCAL file. When the target is a
+    // slug/url we use the file path recorded at publish time. The registry may
+    // not hold a usable local path (the entry was keyed by slug, or the file was
+    // moved/renamed/deleted since publish). In that case, emit a message that
+    // names a local file as the requirement — NOT a misleading
+    // "file not found: https://…" / "file not found: <slug>" that implies the
+    // URL or slug itself is a path.
+    const file = resolved.file;
+    if (file === null || !fs.existsSync(file)) {
+        const where = file !== null && file !== target ? ` (recorded source '${file}')` : "";
+        throw new Error(`tot update needs a local file: '${target}' resolves to a published page but its source` +
+            `${where} is missing — pass the path to the current content`);
+    }
+    const body = fs.readFileSync(file, "utf8");
+    const assetRefs = collectAssetsForPublish(entry.kind, body, file);
+    const assets = prepareAssetRefs(assetRefs);
+    await uploadAssetRefs(deps.http, entry.wsId, assets.filter((asset) => assetNeedsUpload(asset, entry.assets?.[asset.assetPath])));
+    const doc = await putDocument(deps.http, entry.wsId, entry.docId, body, contentTypeFor(entry.kind));
+    entry.bytes = Buffer.byteLength(body, "utf8");
+    entry.assets = registryAssets(assets);
+    if (doc.doc_path)
+        entry.docPath = doc.doc_path;
+    cfg.save();
+    deps.log("");
+    deps.log(`  updated  ${entry.url}`);
+    if (doc.version) {
+        deps.log(`  commit   ${shortCommit(doc.version)}`);
+        deps.log(`  frozen   ${doc.file_url ?? frozenUrl(cfg.contentOrigin, entry.slug, entry.docPath, doc.version)}`);
+    }
+    else {
+        deps.log("  commit   (pending — first save still landing)");
+    }
+    deps.log("");
+}
+function collectAssetsForPublish(kind, body, file) {
+    return kind === "html" ? collectHtmlAssetRefs(body, file) : [];
+}
+function prepareAssetRefs(refs) {
+    const out = [];
+    for (const ref of refs) {
+        if (!fs.existsSync(ref.localPath)) {
+            throw new Error(`local asset not found: ${ref.ref} (${ref.localPath})`);
+        }
+        const stat = fs.statSync(ref.localPath);
+        if (!stat.isFile()) {
+            throw new Error(`local asset is not a file: ${ref.ref} (${ref.localPath})`);
+        }
+        if (stat.size > MAX_ASSET_BYTES) {
+            throw new Error(`local asset too large: ${ref.ref} is ${stat.size} bytes; max is ${MAX_ASSET_BYTES} bytes (${MAX_ASSET_BYTES_LABEL})`);
+        }
+        const bytes = fs.readFileSync(ref.localPath);
+        if (bytes.byteLength > MAX_ASSET_BYTES) {
+            throw new Error(`local asset too large: ${ref.ref} is ${bytes.byteLength} bytes; max is ${MAX_ASSET_BYTES} bytes (${MAX_ASSET_BYTES_LABEL})`);
+        }
+        out.push({
+            ...ref,
+            bytes,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            size: bytes.byteLength,
+        });
+    }
+    return out;
+}
+async function uploadAssetRefs(http, wsId, refs) {
+    await Promise.all(refs.map((ref) => putAsset(http, wsId, ref.assetPath, ref.bytes, ref.contentType)));
+}
+function publishDocPath(file) {
+    const docPath = path.basename(file);
+    if (!validWorkspacePath(docPath)) {
+        throw new Error(`unsupported document path: ${docPath} (no leading/trailing slash, '.', '..', control chars, or \\ ? # %)`);
+    }
+    return docPath;
+}
+function assetNeedsUpload(asset, known) {
+    return (known === undefined ||
+        known.sha256 !== asset.sha256 ||
+        known.contentType !== asset.contentType ||
+        known.size !== asset.size);
+}
+function registryAssets(refs) {
+    if (refs.length === 0)
+        return undefined;
+    return Object.fromEntries(refs.map((ref) => [
+        ref.assetPath,
+        { sha256: ref.sha256, contentType: ref.contentType, size: ref.size },
+    ]));
+}
+/**
+ * `tot remove <file|url|slug>` — hard-delete the page and prune the registry.
+ */
+export async function removeCommand(target, cfg, deps) {
+    const resolved = cfg.resolve(target);
+    if (!resolved) {
+        throw new Error(`not in your registry: ${target} (run 'tot list')`);
+    }
+    const { entry } = resolved;
+    await deleteDocument(deps.http, entry.wsId, entry.docId);
+    cfg.removeEntry(entry.wsId, entry.docId);
+    cfg.save();
+    deps.log(`removed  ${entry.url}`);
+}
+/** `tot list` — purely local; print the pages published from this machine. */
+export function listCommand(cfg, deps) {
+    const entries = Object.entries(cfg.registry);
+    if (entries.length === 0) {
+        deps.log("no pages — publish one with:  tot <file>");
+        return;
+    }
+    deps.log("");
+    for (const [file, entry] of entries) {
+        deps.log(`  ${entry.url}`);
+        deps.log(`    file=${file}  slug=${entry.slug}  ${entry.bytes}b  ${entry.kind}  ${entry.createdAt.slice(0, 19)}`);
+        deps.log("");
+    }
+}
+/** `tot login --key <KEY>` — store a pre-minted key and verify it via /v1/me. */
+export async function loginCommand(key, cfg, deps) {
+    cfg.key = key;
+    // Verify the key works before persisting it (a typo'd key gets a 401 here).
+    const me = await getMe(deps.http);
+    cfg.save();
+    deps.log(`logged in as ${me.email ?? me.user_id}`);
+}

package/dist/config.d.ts

@@ -0,0 +1,64 @@
+/** The /v1 API origin the CLI talks to. A branded alias (api.tot.page) so the
+ * published package is decoupled from infra — repoint the DNS (staging → prod)
+ * without republishing the CLI. */
+export declare const DEFAULT_ENDPOINT = "https://api.tot.page";
+/** The public content origin where living pages are served (the link you share). */
+export declare const DEFAULT_CONTENT_ORIGIN = "https://tot.page";
+export interface RegistryEntry {
+    wsId: string;
+    docId: string;
+    slug: string;
+    url: string;
+    kind: "markdown" | "html";
+    docPath: string;
+    bytes: number;
+    assets?: Record<string, RegistryAssetEntry>;
+    createdAt: string;
+}
+export interface RegistryAssetEntry {
+    sha256: string;
+    contentType: string;
+    size: number;
+}
+/**
+ * The on-disk `~/.tot` state: the API endpoint, an optional key, and a local
+ * registry of pages published from this machine. Anonymous pages have no
+ * server-side owner, so this registry is the only record of what you published
+ * (SPEC §2.6 — "visited-by-link is never listable").
+ */
+export declare class Config {
+    endpoint: string;
+    contentOrigin: string;
+    key: string | null;
+    registry: Record<string, RegistryEntry>;
+    private readonly file;
+    private constructor();
+    /**
+     * Load from disk. A missing file yields defaults. A file that EXISTS but fails
+     * to parse is NOT silently treated as empty — that would let the next save()
+     * overwrite (and permanently destroy) the only record of every anonymous page
+     * published from this machine (SPEC §2.6: pages have no server-side listing).
+     * Instead the corrupt bytes are preserved by renaming the file aside, and we
+     * continue from defaults so the CLI still works going forward.
+     */
+    static load(): Config;
+    /**
+     * Persist to `~/.tot` with owner-only perms (it may hold an API key).
+     * Writes atomically — to a temp file in the same dir, then rename over the
+     * target — so an interrupted write can never half-truncate the registry (the
+     * sole record of anonymous pages).
+     */
+    save(): void;
+    /** Record a freshly-published page, keyed by its local file path. */
+    addEntry(file: string, entry: RegistryEntry): void;
+    getEntryByFile(file: string): RegistryEntry | null;
+    /** Find an entry by slug or by full living URL (for `update`/`remove <url>`). */
+    getEntryBySlug(slugOrUrl: string): RegistryEntry | null;
+    /** Resolve a target that may be a file path, a slug, or a living URL. */
+    resolve(target: string): {
+        file: string | null;
+        entry: RegistryEntry;
+    } | null;
+    /** Remove every registry key pointing at this (wsId, docId) pair. */
+    removeEntry(wsId: string, docId: string): void;
+}

package/dist/config.js

@@ -0,0 +1,143 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** The /v1 API origin the CLI talks to. A branded alias (api.tot.page) so the
+ * published package is decoupled from infra — repoint the DNS (staging → prod)
+ * without republishing the CLI. */
+export const DEFAULT_ENDPOINT = "https://api.tot.page";
+/** The public content origin where living pages are served (the link you share). */
+export const DEFAULT_CONTENT_ORIGIN = "https://tot.page";
+function configPath() {
+    // TOT_CONFIG lets tests point at a temp file instead of the real ~/.tot.
+    return process.env.TOT_CONFIG ?? path.join(os.homedir(), ".tot");
+}
+/**
+ * The on-disk `~/.tot` state: the API endpoint, an optional key, and a local
+ * registry of pages published from this machine. Anonymous pages have no
+ * server-side owner, so this registry is the only record of what you published
+ * (SPEC §2.6 — "visited-by-link is never listable").
+ */
+export class Config {
+    endpoint;
+    contentOrigin;
+    key;
+    registry;
+    file;
+    constructor(file, data) {
+        this.file = file;
+        this.endpoint = data.endpoint;
+        this.contentOrigin = data.contentOrigin;
+        this.key = data.key;
+        this.registry = data.registry;
+    }
+    /**
+     * Load from disk. A missing file yields defaults. A file that EXISTS but fails
+     * to parse is NOT silently treated as empty — that would let the next save()
+     * overwrite (and permanently destroy) the only record of every anonymous page
+     * published from this machine (SPEC §2.6: pages have no server-side listing).
+     * Instead the corrupt bytes are preserved by renaming the file aside, and we
+     * continue from defaults so the CLI still works going forward.
+     */
+    static load() {
+        const file = configPath();
+        let parsed = {};
+        let raw = null;
+        try {
+            raw = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            // File is missing (or unreadable) — start from defaults, nothing to preserve.
+            raw = null;
+        }
+        if (raw !== null) {
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                // The file exists but is corrupt/half-written. Preserve its bytes by
+                // renaming aside BEFORE any later save() can clobber them, so the user
+                // can recover their page list. Then continue from defaults.
+                const backup = `${file}.corrupt.${Date.now()}`;
+                try {
+                    fs.renameSync(file, backup);
+                }
+                catch {
+                    // best-effort — if even the rename fails, we still avoid a silent wipe
+                    // because we never reach here without having tried to preserve the file.
+                }
+                parsed = {};
+            }
+        }
+        return new Config(file, {
+            endpoint: parsed.endpoint ?? DEFAULT_ENDPOINT,
+            contentOrigin: parsed.contentOrigin ?? DEFAULT_CONTENT_ORIGIN,
+            key: parsed.key ?? null,
+            registry: parsed.registry ?? {},
+        });
+    }
+    /**
+     * Persist to `~/.tot` with owner-only perms (it may hold an API key).
+     * Writes atomically — to a temp file in the same dir, then rename over the
+     * target — so an interrupted write can never half-truncate the registry (the
+     * sole record of anonymous pages).
+     */
+    save() {
+        const data = {
+            endpoint: this.endpoint,
+            contentOrigin: this.contentOrigin,
+            key: this.key,
+            registry: this.registry,
+        };
+        const tmp = `${this.file}.tmp.${process.pid}.${Date.now()}`;
+        fs.writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
+        try {
+            // writeFileSync's `mode` only applies on create; chmod covers an existing temp.
+            fs.chmodSync(tmp, 0o600);
+        }
+        catch {
+            // best-effort (e.g. Windows) — not fatal.
+        }
+        // rename is atomic on the same filesystem: readers see either the old file
+        // or the fully-written new one, never a partial.
+        fs.renameSync(tmp, this.file);
+    }
+    /** Record a freshly-published page, keyed by its local file path. */
+    addEntry(file, entry) {
+        this.registry[file] = entry;
+    }
+    getEntryByFile(file) {
+        return this.registry[file] ?? null;
+    }
+    /** Find an entry by slug or by full living URL (for `update`/`remove <url>`). */
+    getEntryBySlug(slugOrUrl) {
+        for (const entry of Object.values(this.registry)) {
+            if (entry.slug === slugOrUrl || entry.url === slugOrUrl)
+                return entry;
+        }
+        return null;
+    }
+    /** Resolve a target that may be a file path, a slug, or a living URL. */
+    resolve(target) {
+        const byFile = this.getEntryByFile(target);
+        if (byFile)
+            return { file: target, entry: byFile };
+        const bySlug = this.getEntryBySlug(target);
+        if (bySlug) {
+            // Find the file key that points at this entry, if any.
+            for (const [file, entry] of Object.entries(this.registry)) {
+                if (entry === bySlug)
+                    return { file, entry };
+            }
+            return { file: null, entry: bySlug };
+        }
+        return null;
+    }
+    /** Remove every registry key pointing at this (wsId, docId) pair. */
+    removeEntry(wsId, docId) {
+        for (const [file, entry] of Object.entries(this.registry)) {
+            if (entry.wsId === wsId && entry.docId === docId) {
+                delete this.registry[file];
+            }
+        }
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,70 @@
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";
+export type HttpBody = string | Uint8Array | ArrayBuffer;
+export interface HttpResponse {
+    status: number;
+    /** Parsed JSON body, or null when the body was empty / not JSON. */
+    json: any;
+    /** Raw response text (kept for error messages and non-JSON bodies). */
+    text: string;
+}
+export interface HttpClient {
+    fetch(method: HttpMethod, path: string, body?: HttpBody | undefined, headers?: Record<string, string>): Promise<HttpResponse>;
+}
+/** Just the bits of `Config` the HTTP layer needs (keeps this module decoupled). */
+export interface HttpConfig {
+    endpoint: string;
+    key: string | null;
+}
+/**
+ * Wraps the global `fetch` into an `HttpClient`. Adds the bearer key (when set)
+ * and a User-Agent, joins the path onto the configured endpoint, and normalizes
+ * every response into `{status, json, text}` so callers never re-parse.
+ */
+export declare function createHttpClient(cfg: HttpConfig, fetchImpl?: typeof fetch): HttpClient;
+/** Pulls the clearest error message out of a non-2xx response. */
+export declare function errorMessage(res: HttpResponse): string;
+export interface DocumentEntity {
+    id: string;
+    workspace_id: string;
+    share_url: string;
+    doc_path: string;
+    kind: "markdown" | "html";
+    title: string | null;
+    version: string | null;
+    body: string;
+    created_at: string;
+    updated_at: string;
+    file_url: string | null;
+}
+export interface WorkspaceEntity {
+    id: string;
+    slug: string;
+    share_url: string;
+    visibility: string;
+}
+export interface CreateDocumentResult {
+    document: DocumentEntity;
+    workspace: WorkspaceEntity;
+}
+export type DocumentKind = "markdown" | "html";
+/** POST /v1/documents — create a new anonymous (open) document. */
+export declare function postDocument(http: HttpClient, kind: DocumentKind, body: string): Promise<CreateDocumentResult>;
+/** POST /v1/workspaces — create an empty workspace shell. */
+export declare function postWorkspace(http: HttpClient): Promise<WorkspaceEntity>;
+/** PUT /v1/workspaces/{wsId}/assets/{assetPath} — upload/replace raw support bytes. */
+export declare function putAsset(http: HttpClient, wsId: string, assetPath: string, body: Uint8Array, contentType: string): Promise<void>;
+/** POST /v1/workspaces/{wsId}/documents — add a document after support files exist. */
+export declare function postWorkspaceDocument(http: HttpClient, wsId: string, docPath: string, kind: DocumentKind, body: string): Promise<DocumentEntity>;
+/** GET /v1/workspaces/{wsId}/documents/{docId} — read current document (JSON). */
+export declare function getDocument(http: HttpClient, wsId: string, docId: string): Promise<DocumentEntity>;
+/** PUT /v1/workspaces/{wsId}/documents/{docId} — replace the raw body. */
+export declare function putDocument(http: HttpClient, wsId: string, docId: string, body: string, contentType: string): Promise<DocumentEntity>;
+/** DELETE /v1/workspaces/{wsId}/documents/{docId} — hard delete (204). */
+export declare function deleteDocument(http: HttpClient, wsId: string, docId: string): Promise<void>;
+export interface MeEntity {
+    user_id: string;
+    email: string | null;
+    active_org_id: string | null;
+}
+/** GET /v1/me — verify a stored key and return the identity behind it. */
+export declare function getMe(http: HttpClient): Promise<MeEntity>;

package/dist/http.js

@@ -0,0 +1,145 @@
+// The injectable HTTP layer. Everything that touches the network goes through an
+// `HttpClient`, so commands can be tested by passing a stub — no live server.
+const USER_AGENT = "tot-cli";
+/**
+ * Wraps the global `fetch` into an `HttpClient`. Adds the bearer key (when set)
+ * and a User-Agent, joins the path onto the configured endpoint, and normalizes
+ * every response into `{status, json, text}` so callers never re-parse.
+ */
+export function createHttpClient(cfg, fetchImpl = fetch) {
+    const base = cfg.endpoint.replace(/\/+$/, "");
+    return {
+        async fetch(method, path, body, headers) {
+            const finalHeaders = {
+                "user-agent": USER_AGENT,
+                ...headers,
+            };
+            if (cfg.key) {
+                finalHeaders["authorization"] = "Bearer " + cfg.key;
+            }
+            let res;
+            try {
+                res = await fetchImpl(base + path, {
+                    method,
+                    headers: finalHeaders,
+                    body,
+                });
+            }
+            catch (cause) {
+                // A DNS/offline/timeout error from fetch is an opaque `TypeError: fetch
+                // failed`. Rethrow with the endpoint so the user can tell a connectivity
+                // problem (or a wrong --endpoint) from a server error.
+                const reason = cause instanceof Error ? cause.message : String(cause);
+                throw new Error(`cannot reach ${base} (${reason}) — check your connection or --endpoint`, { cause });
+            }
+            const text = await res.text();
+            let json = null;
+            if (text.length > 0) {
+                try {
+                    json = JSON.parse(text);
+                }
+                catch {
+                    json = null;
+                }
+            }
+            return { status: res.status, json, text };
+        },
+    };
+}
+/** Pulls the clearest error message out of a non-2xx response. */
+export function errorMessage(res) {
+    if (res.json && typeof res.json === "object") {
+        // The API's error envelope is `{error: {code, message}}` or `{message}`.
+        const e = res.json.error ?? res.json;
+        if (e && typeof e === "object") {
+            if (typeof e.message === "string")
+                return e.message;
+            if (typeof e.code === "string")
+                return e.code;
+        }
+        if (typeof e === "string")
+            return e;
+    }
+    if (res.text)
+        return res.text.slice(0, 500);
+    return `HTTP ${res.status}`;
+}
+/** POST /v1/documents — create a new anonymous (open) document. */
+export async function postDocument(http, kind, body) {
+    const res = await http.fetch("POST", "/v1/documents", JSON.stringify({ kind, body }), {
+        "content-type": "application/json",
+    });
+    if (res.status !== 201 && res.status !== 200) {
+        throw new Error(errorMessage(res));
+    }
+    if (!res.json || !res.json.document || !res.json.workspace) {
+        throw new Error("unexpected create response: missing document/workspace");
+    }
+    return res.json;
+}
+/** POST /v1/workspaces — create an empty workspace shell. */
+export async function postWorkspace(http) {
+    const res = await http.fetch("POST", "/v1/workspaces", JSON.stringify({}), {
+        "content-type": "application/json",
+    });
+    if (res.status !== 201 && res.status !== 200) {
+        throw new Error(errorMessage(res));
+    }
+    if (!res.json || !res.json.workspace) {
+        throw new Error("unexpected create workspace response: missing workspace");
+    }
+    return res.json.workspace;
+}
+/** PUT /v1/workspaces/{wsId}/assets/{assetPath} — upload/replace raw support bytes. */
+export async function putAsset(http, wsId, assetPath, body, contentType) {
+    const res = await http.fetch("PUT", `/v1/workspaces/${encodeURIComponent(wsId)}/assets/${encodeAssetPath(assetPath)}`, body, { "content-type": contentType });
+    if (res.status !== 200) {
+        throw new Error(errorMessage(res));
+    }
+}
+/** POST /v1/workspaces/{wsId}/documents — add a document after support files exist. */
+export async function postWorkspaceDocument(http, wsId, docPath, kind, body) {
+    const res = await http.fetch("POST", `/v1/workspaces/${encodeURIComponent(wsId)}/documents`, JSON.stringify({ doc_path: docPath, kind, body }), { "content-type": "application/json" });
+    if (res.status !== 201 && res.status !== 200) {
+        throw new Error(errorMessage(res));
+    }
+    if (!res.json || !res.json.id) {
+        throw new Error("unexpected add document response: missing document");
+    }
+    return res.json;
+}
+/** GET /v1/workspaces/{wsId}/documents/{docId} — read current document (JSON). */
+export async function getDocument(http, wsId, docId) {
+    const res = await http.fetch("GET", `/v1/workspaces/${encodeURIComponent(wsId)}/documents/${encodeURIComponent(docId)}`, undefined, { accept: "application/json" });
+    if (res.status !== 200) {
+        throw new Error(errorMessage(res));
+    }
+    return res.json;
+}
+/** PUT /v1/workspaces/{wsId}/documents/{docId} — replace the raw body. */
+export async function putDocument(http, wsId, docId, body, contentType) {
+    const res = await http.fetch("PUT", `/v1/workspaces/${encodeURIComponent(wsId)}/documents/${encodeURIComponent(docId)}`, body, { "content-type": contentType });
+    if (res.status !== 200) {
+        throw new Error(errorMessage(res));
+    }
+    return res.json;
+}
+/** DELETE /v1/workspaces/{wsId}/documents/{docId} — hard delete (204). */
+export async function deleteDocument(http, wsId, docId) {
+    const res = await http.fetch("DELETE", `/v1/workspaces/${encodeURIComponent(wsId)}/documents/${encodeURIComponent(docId)}`);
+    // 204 = deleted; 404 = already gone — treat both as success for idempotency.
+    if (res.status !== 204 && res.status !== 404) {
+        throw new Error(errorMessage(res));
+    }
+}
+/** GET /v1/me — verify a stored key and return the identity behind it. */
+export async function getMe(http) {
+    const res = await http.fetch("GET", "/v1/me", undefined, { accept: "application/json" });
+    if (res.status !== 200) {
+        throw new Error(errorMessage(res));
+    }
+    return res.json;
+}
+function encodeAssetPath(assetPath) {
+    return assetPath.split("/").map(encodeURIComponent).join("/");
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./commands.js";
+export * from "./config.js";
+export * from "./http.js";
+export { main } from "./cli.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+// Library surface (the CLI lives in cli.ts). Exposed mostly so the published
+// types resolve and the HTTP/command layer can be reused programmatically.
+export * from "./commands.js";
+export * from "./config.js";
+export * from "./http.js";
+export { main } from "./cli.js";

package/package.json

@@ -0,0 +1,60 @@
+{
+	"name": "@plannotator/tot",
+	"version": "0.1.0",
+	"description": "Publish a markdown or HTML file to a living tot.page URL. A tiny CLI over the Workspaces /v1 API.",
+	"keywords": [
+		"cli",
+		"markdown",
+		"plannotator",
+		"publish",
+		"tot",
+		"tot.page"
+	],
+	"homepage": "https://github.com/plannotator/tot#readme",
+	"bugs": "https://github.com/plannotator/tot/issues",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/plannotator/tot.git"
+	},
+	"bin": {
+		"tot": "dist/cli.js"
+	},
+	"files": [
+		"dist"
+	],
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"lint": "oxlint",
+		"lint:fix": "oxlint --fix",
+		"format": "oxfmt --write .",
+		"format:check": "oxfmt --check .",
+		"typecheck": "tsc --noEmit -p tsconfig.json",
+		"test": "vitest run",
+		"prepublishOnly": "pnpm lint && pnpm typecheck && pnpm test && pnpm build"
+	},
+	"dependencies": {
+		"parse5": "^8.0.1"
+	},
+	"devDependencies": {
+		"@types/node": "^22.19.21",
+		"oxfmt": "^0.43.0",
+		"oxlint": "^1.58.0",
+		"typescript": "6.0.2",
+		"vitest": "^3.0.0"
+	},
+	"engines": {
+		"node": ">=20.19"
+	},
+	"packageManager": "pnpm@10.18.0"
+}