sfora-cli 0.10.0 → 0.11.0

package/dist/web-url.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Where a thing lives on the web — read off the server's answer, never built.
+ *
+ * Card #335. The CLI holds NO route knowledge: it does not know that a document
+ * lives at `/org/<slug>/notes/<id>` or that a card opens as `?detail=card:<id>`,
+ * and it does not know the deployment's web origin. It asks for a path over
+ * `/v1/fs` and prints the link the server put on the answer. That is the whole
+ * contract, and it is why `sfora url` keeps working when the app's routes move.
+ *
+ * The server states it in one of two places, because fs responses come in two
+ * shapes:
+ *
+ *   • a **markdown read** answers with the document's bytes, so the link rides
+ *     in the `X-Sfora-Url` response header — putting it in the file would
+ *     change the canonical bytes every block id is computed over;
+ *   • a **JSON response** (a listing, a `?view=`, a write result) carries a
+ *     top-level `url` field.
+ *
+ * Both are read here so no caller has to care which door it opened.
+ */
+/** The response header a markdown read carries its page link in. */
+export declare const WEB_URL_HEADER = "x-sfora-url";
+/**
+ * The web URL a response names, or null when it names none.
+ *
+ * `body` is the response text when the caller already has it; without it only
+ * the header is consulted. Passing a body that is not JSON is fine — a
+ * markdown read hands its own bytes in and the parse simply fails.
+ */
+export declare function webUrlFromResponse(headers: {
+    get(name: string): string | null;
+}, body?: string): string | null;
+/**
+ * An fs path (`/projects/acme/posts/x.md`) as a `/v1/fs` request path.
+ *
+ * Each segment is encoded on its own so a filename with a space or a `#`
+ * survives, and the separators do not.
+ */
+export declare function fsRequestPath(path: string): string;

package/dist/web-url.js

@@ -0,0 +1,63 @@
+/**
+ * Where a thing lives on the web — read off the server's answer, never built.
+ *
+ * Card #335. The CLI holds NO route knowledge: it does not know that a document
+ * lives at `/org/<slug>/notes/<id>` or that a card opens as `?detail=card:<id>`,
+ * and it does not know the deployment's web origin. It asks for a path over
+ * `/v1/fs` and prints the link the server put on the answer. That is the whole
+ * contract, and it is why `sfora url` keeps working when the app's routes move.
+ *
+ * The server states it in one of two places, because fs responses come in two
+ * shapes:
+ *
+ *   • a **markdown read** answers with the document's bytes, so the link rides
+ *     in the `X-Sfora-Url` response header — putting it in the file would
+ *     change the canonical bytes every block id is computed over;
+ *   • a **JSON response** (a listing, a `?view=`, a write result) carries a
+ *     top-level `url` field.
+ *
+ * Both are read here so no caller has to care which door it opened.
+ */
+/** The response header a markdown read carries its page link in. */
+export const WEB_URL_HEADER = "x-sfora-url";
+/** An absolute `http(s)` URL, or null. Anything else is not a link we print. */
+function absolute(value) {
+    return typeof value === "string" && /^https?:\/\//.test(value) ? value : null;
+}
+/**
+ * The web URL a response names, or null when it names none.
+ *
+ * `body` is the response text when the caller already has it; without it only
+ * the header is consulted. Passing a body that is not JSON is fine — a
+ * markdown read hands its own bytes in and the parse simply fails.
+ */
+export function webUrlFromResponse(headers, body) {
+    const fromHeader = absolute(headers.get(WEB_URL_HEADER));
+    if (fromHeader)
+        return fromHeader;
+    if (!body)
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed && typeof parsed === "object") {
+            return absolute(parsed.url);
+        }
+    }
+    catch {
+        // Not JSON — a markdown body, which says nothing about its page.
+    }
+    return null;
+}
+/**
+ * An fs path (`/projects/acme/posts/x.md`) as a `/v1/fs` request path.
+ *
+ * Each segment is encoded on its own so a filename with a space or a `#`
+ * survives, and the separators do not.
+ */
+export function fsRequestPath(path) {
+    const segments = path
+        .split("/")
+        .filter((s) => s.length > 0)
+        .map(encodeURIComponent);
+    return `/v1/fs${segments.length ? `/${segments.join("/")}` : ""}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sfora-cli",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "Your sfora workspace as a markdown filesystem — a CLI + MCP server. Post/task/doc, ls/cat/grep, and a shell so agents operate sfora natively.",
   "keywords": [