@ferrule-io/ok-fine 0.0.0-stage → 0.3.6

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# ok-fine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A knowledge repository for AI agents. ok-fine stores project knowledge as
+[Open Knowledge Format (OKF) v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+bundles and serves it over **MCP** (stdio or Streamable HTTP) and a **REST JSON API**, protected by OAuth 2.1 bearer tokens
+from your own identity provider.
+
+- One OKF bundle per project; one markdown concept per file with YAML frontmatter.
+- Every change is a git commit, attributed to the writing agent or human, with optional two-way sync to a remote.
+- Full-text keyword search (BM25), trust tiers (`unverified` → `machine-confirmed` → `human-reviewed`), staleness,
+  link graph, and OKF conformance linting.
+- Ships as an npm package (`npx @ferrule-io/ok-fine`), a container image, and a Helm chart.
+
+## Quick start (local)
+
+Requires Node.js 24+ and git. Add ok-fine to Claude Code as a local stdio server (knowledge lives in `~/.ok-fine`):
+
+```sh
+claude mcp add --scope user ok-fine -- npx -y @ferrule-io/ok-fine
+```
+
+Other harnesses: [Coding agents](https://github.com/ferrule-io/ok-fine/wiki/Coding-Agents#local-setup-stdio). Git
+remotes, flags, and several concurrent sessions: [Running locally](https://github.com/ferrule-io/ok-fine/wiki/Running-Locally).
+
+### HTTP server (REST + MCP)
+
+> **Warning:** `--no-auth` / `AUTH_MODE=none` disables authentication completely and gives every caller full admin access. Never expose it beyond localhost.
+
+```sh
+npx -y @ferrule-io/ok-fine serve --no-auth
+```
+
+Or with Docker (requires Docker):
+
+```sh
+docker run --rm -p 127.0.0.1:8080:8080 -e AUTH_MODE=none -e PUBLIC_BASE_URL=http://localhost:8080 -v okf-data:/data ghcr.io/ferrule-io/ok-fine:latest
+```
+
+Or, from a checkout, with Docker Compose (pulls the published image, or builds it from source when the pull fails):
+
+```sh
+docker compose up -d
+```
+
+Create a project, write a concept, and search:
+
+```sh
+curl -s -X POST localhost:8080/api/v1/projects \
+  -H 'x-okf-actor: cli/1.0' \
+  -H 'content-type: application/json' \
+  -d '{"project":"demo","title":"Demo"}'
+
+cat > orders.md <<'EOF'
+---
+type: Reference
+title: Orders
+description: One row per completed customer order.
+tags: [sales]
+---
+
+# Orders
+
+Joined with [customers](/tables/customers.md) on `customer_id`.
+EOF
+
+curl -s -X PUT localhost:8080/api/v1/projects/demo/concepts/tables/orders \
+  -H 'x-okf-actor: cli/1.0' \
+  -H 'content-type: text/markdown' --data-binary @orders.md
+
+curl -s "localhost:8080/api/v1/search?q=orders"
+```
+
+Next, [connect an MCP client](https://github.com/ferrule-io/ok-fine/wiki/Connecting-an-MCP-Client) to `http://localhost:8080/mcp`.
+
+## Documentation
+
+The [wiki](https://github.com/ferrule-io/ok-fine/wiki) covers everything else:
+
+- [Running locally](https://github.com/ferrule-io/ok-fine/wiki/Running-Locally): npm CLI, stdio, flags, git credentials
+- [How it works](https://github.com/ferrule-io/ok-fine/wiki/How-It-Works): data layout, concepts, actors, trust tiers
+- [Connecting an MCP client](https://github.com/ferrule-io/ok-fine/wiki/Connecting-an-MCP-Client)
+- [Using ok-fine from coding agents](https://github.com/ferrule-io/ok-fine/wiki/Coding-Agents): agent package, lifecycle, per-harness setup
+- [MCP tools](https://github.com/ferrule-io/ok-fine/wiki/MCP-Tools)
+- [REST API](https://github.com/ferrule-io/ok-fine/wiki/REST-API)
+- [Authentication and authorization](https://github.com/ferrule-io/ok-fine/wiki/Authentication-and-Authorization)
+- [Git storage and remote sync](https://github.com/ferrule-io/ok-fine/wiki/Git-Storage-and-Remote-Sync)
+- [Configuration](https://github.com/ferrule-io/ok-fine/wiki/Configuration): environment variables
+- [Deploying with Helm](https://github.com/ferrule-io/ok-fine/wiki/Deploying-with-Helm)
+- [Development](https://github.com/ferrule-io/ok-fine/wiki/Development): build, test, layout, CI and releases
+
+## License
+
+[Apache License 2.0](LICENSE).

package/dist/auth/discovery.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+const DiscoveryMetadata = z
+    .object({
+    issuer: z.string(),
+    jwks_uri: z.string().optional(),
+})
+    .passthrough();
+/**
+ * Discovers authorization server metadata via RFC 8414 or OIDC Discovery.
+ * Candidate URLs in order:
+ * 1. origin + "/.well-known/oauth-authorization-server" + p (RFC 8414)
+ * 2. base + "/.well-known/openid-configuration" (OIDC)
+ */
+export async function discoverAuthorizationServer(issuer, options) {
+    const timeoutMs = options?.timeoutMs ?? 5000;
+    const base = issuer.replace(/\/+$/, "");
+    const parsed = new URL(issuer);
+    const origin = parsed.origin;
+    const p = parsed.pathname.replace(/\/+$/, "");
+    const candidateUrls = [
+        `${origin}/.well-known/oauth-authorization-server${p}`,
+        `${base}/.well-known/openid-configuration`,
+    ];
+    let metadata = null;
+    let discoveredJwksUri;
+    for (const candidateUrl of candidateUrls) {
+        try {
+            const res = await fetch(candidateUrl, {
+                signal: AbortSignal.timeout(timeoutMs),
+                headers: { Accept: "application/json" },
+            });
+            if (res.status !== 200) {
+                continue;
+            }
+            const data = await res.json();
+            const parsedMeta = DiscoveryMetadata.safeParse(data);
+            if (parsedMeta.success && parsedMeta.data.issuer === issuer) {
+                metadata = parsedMeta.data;
+                discoveredJwksUri = parsedMeta.data.jwks_uri;
+                break;
+            }
+        }
+        catch {
+            // Try next candidate
+        }
+    }
+    if (!metadata) {
+        throw new Error(`authorization server discovery failed for ${issuer}`);
+    }
+    const jwksUri = options?.jwksUri ?? discoveredJwksUri;
+    if (!jwksUri) {
+        throw new Error(`authorization server discovery failed for ${issuer}: missing jwks_uri`);
+    }
+    return { metadata, jwksUri };
+}
+//# sourceMappingURL=discovery.js.map

package/dist/auth/http-auth.js

@@ -0,0 +1,50 @@
+import { bearerAuthChallengeResponse, OAuthError, OAuthErrorCode, verifyBearerToken, } from "@modelcontextprotocol/server";
+import { principalFromAuthInfo } from "./verifier.js";
+function makeChallengeResponse(error, requiredScopes, resourceMetadataUrl) {
+    const response = bearerAuthChallengeResponse(error, {
+        requiredScopes,
+        resourceMetadataUrl,
+    });
+    const authHeader = response.headers.get("www-authenticate");
+    if (authHeader && !authHeader.includes("scope=")) {
+        const scopeVal = requiredScopes.join(" ");
+        const updatedHeaders = new Headers(response.headers);
+        updatedHeaders.set("www-authenticate", `${authHeader}, scope="${scopeVal}"`);
+        return new Response(response.body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: updatedHeaders,
+        });
+    }
+    return response;
+}
+/**
+ * Creates an authenticator for HTTP requests that validates Bearer tokens
+ * against the verifier and produces standard RFC 9728 / RFC 6750 challenge responses.
+ */
+export function createAuthenticator(options) {
+    const { verifier, resourceMetadataUrl, scopeNames } = options;
+    async function authenticate(authorizationHeader) {
+        try {
+            const authInfo = await verifyBearerToken(authorizationHeader, {
+                verifier,
+                resourceMetadataUrl,
+            });
+            const principal = principalFromAuthInfo(authInfo, scopeNames);
+            if (!principal.canRead) {
+                const response = makeChallengeResponse(new OAuthError(OAuthErrorCode.InsufficientScope, "token carries no ok-fine scope"), [scopeNames.read], resourceMetadataUrl);
+                return { ok: false, response };
+            }
+            return { ok: true, authInfo, principal };
+        }
+        catch (err) {
+            const response = makeChallengeResponse(err, [scopeNames.read, scopeNames.write], resourceMetadataUrl);
+            return { ok: false, response };
+        }
+    }
+    function insufficientScope(scopeName) {
+        return makeChallengeResponse(new OAuthError(OAuthErrorCode.InsufficientScope, `requires ${scopeName}`), [scopeName], resourceMetadataUrl);
+    }
+    return { authenticate, insufficientScope };
+}
+//# sourceMappingURL=http-auth.js.map

package/dist/auth/verifier.js

@@ -0,0 +1,133 @@
+import { OAuthError, OAuthErrorCode } from "@modelcontextprotocol/server";
+import { createRemoteJWKSet, errors, jwtVerify } from "jose";
+/**
+ * Validates JWT access tokens against a remote JWKS.
+ */
+export class JwtTokenVerifier {
+    issuer;
+    audiences;
+    identityClaims;
+    jwks;
+    constructor(options) {
+        this.issuer = options.issuer;
+        this.audiences = options.audiences;
+        this.identityClaims = options.identityClaims;
+        this.jwks = createRemoteJWKSet(new URL(options.jwksUri), {
+            cooldownDuration: 30000,
+            cacheMaxAge: 600000,
+            timeoutDuration: 5000,
+        });
+    }
+    async verifyAccessToken(token) {
+        let result;
+        try {
+            result = await jwtVerify(token, this.jwks, {
+                issuer: this.issuer,
+                audience: this.audiences,
+                clockTolerance: 30,
+            });
+        }
+        catch (err) {
+            if (err instanceof errors.JWTExpired) {
+                throw new OAuthError(OAuthErrorCode.InvalidToken, "token expired");
+            }
+            if (err instanceof errors.JWTClaimValidationFailed) {
+                const claim = err.claim || "claim";
+                throw new OAuthError(OAuthErrorCode.InvalidToken, `invalid ${claim} claim`);
+            }
+            if (err instanceof errors.JWKSTimeout) {
+                throw new OAuthError(OAuthErrorCode.ServerError, "JWKS fetch timed out");
+            }
+            throw new OAuthError(OAuthErrorCode.InvalidToken, "invalid token");
+        }
+        const payload = result.payload;
+        if (typeof payload.exp !== "number") {
+            throw new OAuthError(OAuthErrorCode.InvalidToken, "token has no exp");
+        }
+        const scopeSet = new Set();
+        if (typeof payload.scope === "string") {
+            for (const s of payload.scope.trim().split(/\s+/)) {
+                if (s.length > 0) {
+                    scopeSet.add(s);
+                }
+            }
+        }
+        if (typeof payload.scp === "string") {
+            for (const s of payload.scp.trim().split(/\s+/)) {
+                if (s.length > 0) {
+                    scopeSet.add(s);
+                }
+            }
+        }
+        else if (Array.isArray(payload.scp)) {
+            for (const s of payload.scp) {
+                if (typeof s === "string" && s.trim().length > 0) {
+                    scopeSet.add(s.trim());
+                }
+            }
+        }
+        if (Array.isArray(payload.permissions)) {
+            for (const p of payload.permissions) {
+                if (typeof p === "string" && p.trim().length > 0) {
+                    scopeSet.add(p.trim());
+                }
+            }
+        }
+        const scopes = Array.from(scopeSet);
+        let clientId = "unknown";
+        for (const field of ["azp", "client_id", "cid"]) {
+            const val = payload[field];
+            if (typeof val === "string" && val.length > 0) {
+                clientId = val;
+                break;
+            }
+        }
+        let identity = null;
+        for (const claim of this.identityClaims) {
+            const val = payload[claim];
+            if (typeof val === "string" && val.trim().length > 0) {
+                identity = val.trim();
+                break;
+            }
+        }
+        return {
+            token,
+            clientId,
+            scopes,
+            expiresAt: payload.exp,
+            extra: {
+                sub: typeof payload.sub === "string" ? payload.sub : "unknown",
+                identity,
+            },
+        };
+    }
+}
+/**
+ * Computes a Principal from an AuthInfo and configured scope names.
+ * Hierarchy:
+ * - canAdmin = has admin scope
+ * - canWrite = write or admin
+ * - canRead = read, write, or admin
+ */
+export function principalFromAuthInfo(info, scopeNames) {
+    const hasAdmin = info.scopes.includes(scopeNames.admin);
+    const hasWrite = info.scopes.includes(scopeNames.write);
+    const hasRead = info.scopes.includes(scopeNames.read);
+    const canAdmin = hasAdmin;
+    const canWrite = hasWrite || hasAdmin;
+    const canRead = hasRead || hasWrite || hasAdmin;
+    const extraSub = info.extra?.sub;
+    const extraIdentity = info.extra?.identity;
+    const sub = typeof extraSub === "string" ? extraSub : "unknown";
+    const identity = typeof extraIdentity === "string" ? extraIdentity : null;
+    return {
+        subject: sub,
+        clientId: info.clientId,
+        identity,
+        scopes: info.scopes,
+        canRead,
+        canWrite,
+        canAdmin,
+    };
+}
+//# sourceMappingURL=verifier.js.map

package/dist/cli-options.js

@@ -0,0 +1,99 @@
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+export const USAGE = `Usage: ok-fine [stdio|serve] [options]
+
+Commands:
+  stdio (default)          Serve MCP over stdin/stdout for one local client
+  serve                    Serve MCP and the REST API over HTTP
+
+Options:
+  --data-dir <path>        Knowledge repository location (DATA_DIR, default ~/.ok-fine)
+  --remote <url>           Git remote to sync with, using your git credentials (GIT_REMOTE_URL)
+  --branch <name>          Git branch (GIT_BRANCH, default main)
+  --sync-interval <sec>    Periodic sync interval, 0 disables (GIT_SYNC_INTERVAL_SECONDS, default 60)
+  --log-level <level>      fatal|error|warn|info|debug|trace|silent (LOG_LEVEL, default info)
+  -h, --help               Show this help
+  -v, --version            Print the version
+
+serve options:
+  --port <port>            PORT, default 8080
+  --host <addr>            HOST, default 127.0.0.1
+  --public-base-url <url>  PUBLIC_BASE_URL, default http://localhost:<port>
+  --no-auth                AUTH_MODE=none: no authentication, every caller is admin; localhost only
+
+Every variable in https://github.com/ferrule-io/ok-fine/wiki/Configuration also works; flags win.
+`;
+const FLAG_ENV = {
+    "data-dir": "DATA_DIR",
+    remote: "GIT_REMOTE_URL",
+    branch: "GIT_BRANCH",
+    "sync-interval": "GIT_SYNC_INTERVAL_SECONDS",
+    "log-level": "LOG_LEVEL",
+    port: "PORT",
+    host: "HOST",
+    "public-base-url": "PUBLIC_BASE_URL",
+};
+const SERVE_ONLY_FLAGS = ["port", "host", "public-base-url", "no-auth"];
+/** Pure: maps argv and the process env to a command and the env its config loader reads. Throws on bad usage. */
+export function parseCli(argv, env, homeDir) {
+    // --help/--version win over everything else, including unknown flags and bad commands.
+    const flags = argv.includes("--") ? argv.slice(0, argv.indexOf("--")) : argv;
+    if (flags.includes("--help") || flags.includes("-h"))
+        return { command: "help", env };
+    if (flags.includes("--version") || flags.includes("-v"))
+        return { command: "version", env };
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        strict: true,
+        options: {
+            "data-dir": { type: "string" },
+            remote: { type: "string" },
+            branch: { type: "string" },
+            "sync-interval": { type: "string" },
+            "log-level": { type: "string" },
+            port: { type: "string" },
+            host: { type: "string" },
+            "public-base-url": { type: "string" },
+            "no-auth": { type: "boolean" },
+        },
+    });
+    let command;
+    if (positionals.length === 0 || (positionals.length === 1 && positionals[0] === "stdio")) {
+        command = "stdio";
+    }
+    else if (positionals.length === 1 && positionals[0] === "serve") {
+        command = "serve";
+    }
+    else {
+        throw new Error(`unknown command "${positionals.join(" ")}"`);
+    }
+    if (command === "stdio") {
+        for (const name of SERVE_ONLY_FLAGS) {
+            if (values[name] !== undefined)
+                throw new Error(`--${name} only applies to "ok-fine serve"`);
+        }
+    }
+    const flagEnv = {};
+    for (const [flag, envName] of Object.entries(FLAG_ENV)) {
+        const value = values[flag];
+        if (typeof value === "string")
+            flagEnv[envName] = value;
+    }
+    const dataDirFlag = values["data-dir"];
+    if (dataDirFlag !== undefined) {
+        const expanded = dataDirFlag === "~" ? homeDir : dataDirFlag.startsWith("~/") ? join(homeDir, dataDirFlag.slice(2)) : dataDirFlag;
+        flagEnv.DATA_DIR = resolve(expanded);
+    }
+    if (values["no-auth"])
+        flagEnv.AUTH_MODE = "none";
+    const defaults = { DATA_DIR: join(homeDir, ".ok-fine") };
+    if (command === "serve")
+        defaults.HOST = "127.0.0.1";
+    const merged = { ...defaults, ...env, ...flagEnv };
+    if (command === "serve" && merged.PUBLIC_BASE_URL === undefined) {
+        merged.PUBLIC_BASE_URL = `http://localhost:${merged.PORT ?? "8080"}`;
+    }
+    return { command, env: merged };
+}
+//# sourceMappingURL=cli-options.js.map