@obrigado/surface 0.1.0

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

@@ -0,0 +1,36 @@
+# @obrigado/surface
+
+What a host that draws its own UI needs from [Obrigado](https://obrigado.dev)'s renderer, and
+nothing else.
+
+Obrigado puts one labeled sponsored line in a coding agent's status line, and 70% of the
+revenue funds the open-source packages the developer's project depends on. There is one
+renderer, `obrigado statusline`, and every host serialises from it. A host that composes the
+line from parts rather than printing an ANSI string — OpenCode's TUI plugin, the VS Code
+extension — runs `obrigado statusline --agent <host> --json` and draws what it is handed.
+
+This package is the three things every such host needs, once, with no dependencies and no I/O:
+
+- **The shape** of one `--json` line: `Sponsored`, `SponsoredSpan`, `SponsoredBrand`, and the
+  palette a span may ask for.
+- **`parseSponsored(line)`** — a complete line, or `null`. Label, copy and URL or nothing: a
+  creative without its label is an undisclosed advertisement, and one without its URL is an
+  impression nobody can act on. Unknown colours degrade to the host's foreground.
+- **`statuslineArgv(agent, override?)`** and **`splitCommand(text)`** — the argv to spawn, with
+  a quote-aware split so a source checkout under a path with a space still runs.
+
+```ts
+import { parseSponsored, statuslineArgv } from "@obrigado/surface";
+
+const [bin, ...args] = statuslineArgv("my-host", process.env["OBRIGADO_STATUSLINE_COMMAND"]);
+// spawn bin with args, write `{ "session_id": …, "cwd": … }` to stdin, read the first line
+const ad = parseSponsored(firstLine);
+if (ad !== null) draw(ad.label, ad.spans, ad.url);
+```
+
+A host never fetches, counts or formats an ad itself; rotation, batching, beacons and the
+disclosure stay in the renderer. That is what keeps "always labeled" a property rather than a
+convention. To add a host, see `docs/ADDING-A-SURFACE.md` in the
+[client repository](https://github.com/obrigado-dev/client).
+
+Apache-2.0.

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * What a host that draws its own UI needs from the renderer, and nothing else.
+ *
+ * INVARIANT 13: there is one renderer, and every host serialises from it. A host package —
+ * the OpenCode plugin, the VS Code extension — runs `obrigado statusline --json` and composes
+ * the parts it is handed with its own primitives. It never fetches, counts or formats an ad.
+ * That boundary is what keeps "always labeled" a property rather than a convention, and it is
+ * why host packages import nothing from `@obrigado/shared`: the wire contract, the money and
+ * the rotation are the renderer's business.
+ *
+ * What the hosts DID each carry was a copy of the same three things — the shape of one `--json`
+ * line, the checks that decide whether a line is complete enough to draw, and the splitting of
+ * a configured command into an argv. Three copies drift: the palette had reached five spellings,
+ * and every copy of the argv split broke on a path with a space in it. This package is those
+ * three things, once, with no dependencies and no I/O. It speaks no HTTP and reads no file, so
+ * depending on it changes nothing about what a host is allowed to do.
+ *
+ * The Pi extension does not depend on it, deliberately: that file is COPIED into a developer's
+ * extensions directory and must stand alone. It keeps its own copy of `splitCommand`, and a test
+ * in its package holds the two to the same behaviour.
+ */
+/**
+ * The four colours a creative may wear. Never red or yellow: in a terminal those mean error
+ * and warning, and an ad wearing either is impersonating a build failure. This is the one
+ * copy the hosts see; `@obrigado/shared`'s contract is the other, and a test in the client
+ * package holds the two together.
+ */
+export declare const SPAN_COLORS: readonly ["cyan", "blue", "green", "magenta"];
+export type SpanColor = (typeof SPAN_COLORS)[number];
+/** Line-level colour slot; `default` means the host's own foreground. */
+export declare const LINE_STYLES: readonly ["default", "cyan", "blue", "green", "magenta"];
+export type LineStyle = (typeof LINE_STYLES)[number];
+/** Line-level effect. Nothing louder than italic is offered, so nothing louder is drawn. */
+export declare const LINE_EFFECTS: readonly ["none", "italic"];
+export type LineEffect = (typeof LINE_EFFECTS)[number];
+/** A run of styled text, as the renderer serialises it. */
+export interface SponsoredSpan {
+    readonly text: string;
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    /** Reverse video in a terminal; a host with no such thing ignores it. */
+    readonly highlight?: boolean;
+    /** One of the four slots an advertiser may choose. */
+    readonly color?: SpanColor;
+    /** Part of the single tracking link whose URL is `Sponsored.url`. */
+    readonly link?: boolean;
+}
+/** Who is paying, as they name themselves. */
+export interface SponsoredBrand {
+    readonly name: string;
+    /** A `data:image/png;base64,…` URI built server-side from validated bytes, or null. Never a URL. */
+    readonly logo: string | null;
+}
+/** One `--json` line from `obrigado statusline`. */
+export interface Sponsored {
+    /** The disclosure. A host renders it before the copy, always, and never styles it. */
+    readonly label: string;
+    /** The plain copy: the accessible fallback, and the form that belongs in a log. */
+    readonly copy: string;
+    /** The click redirect, `https://obrigado.dev/c/<token>`. */
+    readonly url: string;
+    readonly spans: readonly SponsoredSpan[];
+    readonly style: LineStyle;
+    readonly effect: LineEffect;
+    readonly brand: SponsoredBrand | null;
+}
+/**
+ * One line of `--json` output, or null for anything that is not a complete sponsored line.
+ *
+ * Label, copy and URL, or nothing: a creative without its label is an undisclosed
+ * advertisement, and one without its URL is an impression nobody can act on. Styling is
+ * optional on the wire — an older renderer that sends none still renders, as one unstyled link
+ * over the whole line. A brand without a name is not a brand; the alt text for a logo IS the
+ * name, so a malformed one is dropped rather than rendered half-way.
+ */
+export declare function parseSponsored(line: string): Sponsored | null;
+/**
+ * A configured command, split the way a shell would split it — quotes and all.
+ *
+ * `OBRIGADO_STATUSLINE_COMMAND` exists so a host can run a source checkout, and a checkout
+ * lives at a path. Splitting on spaces broke the moment that path contained one: `bun
+ * "/Users/Jane Doe/obrigado/cli.ts" statusline` became four arguments and the spawn failed
+ * silently. Double quotes, single quotes and backslash escapes are honoured; nothing else is
+ * interpreted — no variables, no globs, no operators — because this is a command, not a script.
+ */
+export declare function splitCommand(text: string): string[];
+/**
+ * The argv a host spawns to get its line.
+ *
+ * `obrigado` from PATH is the installed case. An override — a setting, an environment
+ * variable — replaces the executable and its leading arguments and keeps everything after:
+ * the host names itself so the impression attributes to it, and asks for `--json` because it
+ * draws with its own primitives rather than printing an ANSI string.
+ */
+export declare function statuslineArgv(agent: string, override?: string | undefined, options?: {
+    readonly json?: boolean;
+}): string[];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,WAAW,+CAAgD,CAAC;AACzE,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,yEAAyE;AACzE,eAAO,MAAM,WAAW,0DAAuC,CAAC;AAChE,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,4FAA4F;AAC5F,eAAO,MAAM,YAAY,6BAA8B,CAAC;AACxD,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAUvD,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oGAAoG;IACpG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,oDAAoD;AACpD,MAAM,WAAW,SAAS;IACxB,sFAAsF;IACtF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;CACvC;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CA6B7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAqCnD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,EAC7B,OAAO,GAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GACxC,MAAM,EAAE,CAIV"}

package/dist/index.js

@@ -0,0 +1,90 @@
+// src/index.ts
+var SPAN_COLORS = ["cyan", "blue", "green", "magenta"];
+var LINE_STYLES = ["default", ...SPAN_COLORS];
+var LINE_EFFECTS = ["none", "italic"];
+function isLineStyle(value) {
+  return typeof value === "string" && LINE_STYLES.includes(value);
+}
+function isLineEffect(value) {
+  return typeof value === "string" && LINE_EFFECTS.includes(value);
+}
+function parseSponsored(line) {
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null)
+    return null;
+  const { label, copy, url, spans, style, effect, brand } = parsed;
+  if (typeof label !== "string" || typeof copy !== "string" || typeof url !== "string") {
+    return null;
+  }
+  if (label.length === 0 || copy.length === 0 || url.length === 0)
+    return null;
+  return {
+    label,
+    copy,
+    url,
+    spans: Array.isArray(spans) && spans.length > 0 ? spans : [{ text: copy, link: true }],
+    style: isLineStyle(style) ? style : "default",
+    effect: isLineEffect(effect) ? effect : "none",
+    brand: brand !== null && brand !== undefined && typeof brand.name === "string" ? { name: brand.name, logo: typeof brand.logo === "string" ? brand.logo : null } : null
+  };
+}
+function splitCommand(text) {
+  const out = [];
+  let current = "";
+  let inToken = false;
+  let quote = null;
+  for (let index = 0;index < text.length; index += 1) {
+    const character = text[index] ?? "";
+    if (quote !== null) {
+      if (character === quote) {
+        quote = null;
+      } else if (character === "\\" && quote === '"' && index + 1 < text.length) {
+        index += 1;
+        current += text[index] ?? "";
+      } else {
+        current += character;
+      }
+      continue;
+    }
+    if (character === '"' || character === "'") {
+      quote = character;
+      inToken = true;
+    } else if (character === "\\" && index + 1 < text.length) {
+      index += 1;
+      current += text[index] ?? "";
+      inToken = true;
+    } else if (/\s/u.test(character)) {
+      if (inToken)
+        out.push(current);
+      current = "";
+      inToken = false;
+    } else {
+      current += character;
+      inToken = true;
+    }
+  }
+  if (inToken)
+    out.push(current);
+  return out;
+}
+function statuslineArgv(agent, override, options = {}) {
+  const configured = override?.trim() ?? "";
+  const base = configured.length > 0 ? splitCommand(configured) : ["obrigado", "statusline"];
+  return [...base, "--agent", agent, ...options.json === false ? [] : ["--json"]];
+}
+export {
+  statuslineArgv,
+  splitCommand,
+  parseSponsored,
+  SPAN_COLORS,
+  LINE_STYLES,
+  LINE_EFFECTS
+};
+
+//# debugId=A0FDAF5235B084AD64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": [
+    "/**\n * What a host that draws its own UI needs from the renderer, and nothing else.\n *\n * INVARIANT 13: there is one renderer, and every host serialises from it. A host package —\n * the OpenCode plugin, the VS Code extension — runs `obrigado statusline --json` and composes\n * the parts it is handed with its own primitives. It never fetches, counts or formats an ad.\n * That boundary is what keeps \"always labeled\" a property rather than a convention, and it is\n * why host packages import nothing from `@obrigado/shared`: the wire contract, the money and\n * the rotation are the renderer's business.\n *\n * What the hosts DID each carry was a copy of the same three things — the shape of one `--json`\n * line, the checks that decide whether a line is complete enough to draw, and the splitting of\n * a configured command into an argv. Three copies drift: the palette had reached five spellings,\n * and every copy of the argv split broke on a path with a space in it. This package is those\n * three things, once, with no dependencies and no I/O. It speaks no HTTP and reads no file, so\n * depending on it changes nothing about what a host is allowed to do.\n *\n * The Pi extension does not depend on it, deliberately: that file is COPIED into a developer's\n * extensions directory and must stand alone. It keeps its own copy of `splitCommand`, and a test\n * in its package holds the two to the same behaviour.\n */\n\n/**\n * The four colours a creative may wear. Never red or yellow: in a terminal those mean error\n * and warning, and an ad wearing either is impersonating a build failure. This is the one\n * copy the hosts see; `@obrigado/shared`'s contract is the other, and a test in the client\n * package holds the two together.\n */\nexport const SPAN_COLORS = [\"cyan\", \"blue\", \"green\", \"magenta\"] as const;\nexport type SpanColor = (typeof SPAN_COLORS)[number];\n\n/** Line-level colour slot; `default` means the host's own foreground. */\nexport const LINE_STYLES = [\"default\", ...SPAN_COLORS] as const;\nexport type LineStyle = (typeof LINE_STYLES)[number];\n\n/** Line-level effect. Nothing louder than italic is offered, so nothing louder is drawn. */\nexport const LINE_EFFECTS = [\"none\", \"italic\"] as const;\nexport type LineEffect = (typeof LINE_EFFECTS)[number];\n\nfunction isLineStyle(value: unknown): value is LineStyle {\n  return typeof value === \"string\" && (LINE_STYLES as readonly string[]).includes(value);\n}\n\nfunction isLineEffect(value: unknown): value is LineEffect {\n  return typeof value === \"string\" && (LINE_EFFECTS as readonly string[]).includes(value);\n}\n\n/** A run of styled text, as the renderer serialises it. */\nexport interface SponsoredSpan {\n  readonly text: string;\n  readonly bold?: boolean;\n  readonly italic?: boolean;\n  /** Reverse video in a terminal; a host with no such thing ignores it. */\n  readonly highlight?: boolean;\n  /** One of the four slots an advertiser may choose. */\n  readonly color?: SpanColor;\n  /** Part of the single tracking link whose URL is `Sponsored.url`. */\n  readonly link?: boolean;\n}\n\n/** Who is paying, as they name themselves. */\nexport interface SponsoredBrand {\n  readonly name: string;\n  /** A `data:image/png;base64,…` URI built server-side from validated bytes, or null. Never a URL. */\n  readonly logo: string | null;\n}\n\n/** One `--json` line from `obrigado statusline`. */\nexport interface Sponsored {\n  /** The disclosure. A host renders it before the copy, always, and never styles it. */\n  readonly label: string;\n  /** The plain copy: the accessible fallback, and the form that belongs in a log. */\n  readonly copy: string;\n  /** The click redirect, `https://obrigado.dev/c/<token>`. */\n  readonly url: string;\n  readonly spans: readonly SponsoredSpan[];\n  readonly style: LineStyle;\n  readonly effect: LineEffect;\n  readonly brand: SponsoredBrand | null;\n}\n\n/**\n * One line of `--json` output, or null for anything that is not a complete sponsored line.\n *\n * Label, copy and URL, or nothing: a creative without its label is an undisclosed\n * advertisement, and one without its URL is an impression nobody can act on. Styling is\n * optional on the wire — an older renderer that sends none still renders, as one unstyled link\n * over the whole line. A brand without a name is not a brand; the alt text for a logo IS the\n * name, so a malformed one is dropped rather than rendered half-way.\n */\nexport function parseSponsored(line: string): Sponsored | null {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(line);\n  } catch {\n    return null;\n  }\n  if (typeof parsed !== \"object\" || parsed === null) return null;\n\n  const { label, copy, url, spans, style, effect, brand } = parsed as Partial<Sponsored>;\n  if (typeof label !== \"string\" || typeof copy !== \"string\" || typeof url !== \"string\") {\n    return null;\n  }\n  if (label.length === 0 || copy.length === 0 || url.length === 0) return null;\n\n  return {\n    label,\n    copy,\n    url,\n    spans: Array.isArray(spans) && spans.length > 0 ? spans : [{ text: copy, link: true }],\n    // A slot or effect this copy does not know is drawn as none: a newer renderer's colour\n    // must degrade to the host's foreground, never to a string the host cannot parse.\n    style: isLineStyle(style) ? style : \"default\",\n    effect: isLineEffect(effect) ? effect : \"none\",\n    brand:\n      brand !== null && brand !== undefined && typeof brand.name === \"string\"\n        ? { name: brand.name, logo: typeof brand.logo === \"string\" ? brand.logo : null }\n        : null,\n  };\n}\n\n/**\n * A configured command, split the way a shell would split it — quotes and all.\n *\n * `OBRIGADO_STATUSLINE_COMMAND` exists so a host can run a source checkout, and a checkout\n * lives at a path. Splitting on spaces broke the moment that path contained one: `bun\n * \"/Users/Jane Doe/obrigado/cli.ts\" statusline` became four arguments and the spawn failed\n * silently. Double quotes, single quotes and backslash escapes are honoured; nothing else is\n * interpreted — no variables, no globs, no operators — because this is a command, not a script.\n */\nexport function splitCommand(text: string): string[] {\n  const out: string[] = [];\n  let current = \"\";\n  let inToken = false;\n  let quote: '\"' | \"'\" | null = null;\n\n  for (let index = 0; index < text.length; index += 1) {\n    const character = text[index] ?? \"\";\n    if (quote !== null) {\n      if (character === quote) {\n        quote = null;\n      } else if (character === \"\\\\\" && quote === '\"' && index + 1 < text.length) {\n        index += 1;\n        current += text[index] ?? \"\";\n      } else {\n        current += character;\n      }\n      continue;\n    }\n    if (character === '\"' || character === \"'\") {\n      quote = character;\n      inToken = true;\n    } else if (character === \"\\\\\" && index + 1 < text.length) {\n      index += 1;\n      current += text[index] ?? \"\";\n      inToken = true;\n    } else if (/\\s/u.test(character)) {\n      if (inToken) out.push(current);\n      current = \"\";\n      inToken = false;\n    } else {\n      current += character;\n      inToken = true;\n    }\n  }\n  if (inToken) out.push(current);\n  return out;\n}\n\n/**\n * The argv a host spawns to get its line.\n *\n * `obrigado` from PATH is the installed case. An override — a setting, an environment\n * variable — replaces the executable and its leading arguments and keeps everything after:\n * the host names itself so the impression attributes to it, and asks for `--json` because it\n * draws with its own primitives rather than printing an ANSI string.\n */\nexport function statuslineArgv(\n  agent: string,\n  override?: string | undefined,\n  options: { readonly json?: boolean } = {},\n): string[] {\n  const configured = override?.trim() ?? \"\";\n  const base = configured.length > 0 ? splitCommand(configured) : [\"obrigado\", \"statusline\"];\n  return [...base, \"--agent\", agent, ...(options.json === false ? [] : [\"--json\"])];\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "A0FDAF5235B084AD64756E2164756E21",
+  "names": []
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@obrigado/surface",
+  "version": "0.1.0",
+  "description": "What an Obrigado host composes: the `obrigado statusline --json` shape, its parser, and how to invoke the renderer.",
+  "keywords": [
+    "coding-agent",
+    "obrigado",
+    "opencode",
+    "sponsored",
+    "statusline",
+    "vscode"
+  ],
+  "homepage": "https://obrigado.dev",
+  "bugs": {
+    "url": "https://github.com/obrigado-dev/client/issues"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/obrigado-dev/client.git",
+    "directory": "packages/surface"
+  },
+  "files": [
+    "LICENSE",
+    "dist/index.js",
+    "dist/index.js.map",
+    "dist/index.d.ts",
+    "dist/index.d.ts.map",
+    "src/index.ts"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node --format esm --sourcemap=linked && tsc --build tsconfig.json --force",
+    "prepack": "bun run build"
+  }
+}

package/src/index.ts

@@ -0,0 +1,186 @@
+/**
+ * What a host that draws its own UI needs from the renderer, and nothing else.
+ *
+ * INVARIANT 13: there is one renderer, and every host serialises from it. A host package —
+ * the OpenCode plugin, the VS Code extension — runs `obrigado statusline --json` and composes
+ * the parts it is handed with its own primitives. It never fetches, counts or formats an ad.
+ * That boundary is what keeps "always labeled" a property rather than a convention, and it is
+ * why host packages import nothing from `@obrigado/shared`: the wire contract, the money and
+ * the rotation are the renderer's business.
+ *
+ * What the hosts DID each carry was a copy of the same three things — the shape of one `--json`
+ * line, the checks that decide whether a line is complete enough to draw, and the splitting of
+ * a configured command into an argv. Three copies drift: the palette had reached five spellings,
+ * and every copy of the argv split broke on a path with a space in it. This package is those
+ * three things, once, with no dependencies and no I/O. It speaks no HTTP and reads no file, so
+ * depending on it changes nothing about what a host is allowed to do.
+ *
+ * The Pi extension does not depend on it, deliberately: that file is COPIED into a developer's
+ * extensions directory and must stand alone. It keeps its own copy of `splitCommand`, and a test
+ * in its package holds the two to the same behaviour.
+ */
+
+/**
+ * The four colours a creative may wear. Never red or yellow: in a terminal those mean error
+ * and warning, and an ad wearing either is impersonating a build failure. This is the one
+ * copy the hosts see; `@obrigado/shared`'s contract is the other, and a test in the client
+ * package holds the two together.
+ */
+export const SPAN_COLORS = ["cyan", "blue", "green", "magenta"] as const;
+export type SpanColor = (typeof SPAN_COLORS)[number];
+
+/** Line-level colour slot; `default` means the host's own foreground. */
+export const LINE_STYLES = ["default", ...SPAN_COLORS] as const;
+export type LineStyle = (typeof LINE_STYLES)[number];
+
+/** Line-level effect. Nothing louder than italic is offered, so nothing louder is drawn. */
+export const LINE_EFFECTS = ["none", "italic"] as const;
+export type LineEffect = (typeof LINE_EFFECTS)[number];
+
+function isLineStyle(value: unknown): value is LineStyle {
+  return typeof value === "string" && (LINE_STYLES as readonly string[]).includes(value);
+}
+
+function isLineEffect(value: unknown): value is LineEffect {
+  return typeof value === "string" && (LINE_EFFECTS as readonly string[]).includes(value);
+}
+
+/** A run of styled text, as the renderer serialises it. */
+export interface SponsoredSpan {
+  readonly text: string;
+  readonly bold?: boolean;
+  readonly italic?: boolean;
+  /** Reverse video in a terminal; a host with no such thing ignores it. */
+  readonly highlight?: boolean;
+  /** One of the four slots an advertiser may choose. */
+  readonly color?: SpanColor;
+  /** Part of the single tracking link whose URL is `Sponsored.url`. */
+  readonly link?: boolean;
+}
+
+/** Who is paying, as they name themselves. */
+export interface SponsoredBrand {
+  readonly name: string;
+  /** A `data:image/png;base64,…` URI built server-side from validated bytes, or null. Never a URL. */
+  readonly logo: string | null;
+}
+
+/** One `--json` line from `obrigado statusline`. */
+export interface Sponsored {
+  /** The disclosure. A host renders it before the copy, always, and never styles it. */
+  readonly label: string;
+  /** The plain copy: the accessible fallback, and the form that belongs in a log. */
+  readonly copy: string;
+  /** The click redirect, `https://obrigado.dev/c/<token>`. */
+  readonly url: string;
+  readonly spans: readonly SponsoredSpan[];
+  readonly style: LineStyle;
+  readonly effect: LineEffect;
+  readonly brand: SponsoredBrand | null;
+}
+
+/**
+ * One line of `--json` output, or null for anything that is not a complete sponsored line.
+ *
+ * Label, copy and URL, or nothing: a creative without its label is an undisclosed
+ * advertisement, and one without its URL is an impression nobody can act on. Styling is
+ * optional on the wire — an older renderer that sends none still renders, as one unstyled link
+ * over the whole line. A brand without a name is not a brand; the alt text for a logo IS the
+ * name, so a malformed one is dropped rather than rendered half-way.
+ */
+export function parseSponsored(line: string): Sponsored | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+
+  const { label, copy, url, spans, style, effect, brand } = parsed as Partial<Sponsored>;
+  if (typeof label !== "string" || typeof copy !== "string" || typeof url !== "string") {
+    return null;
+  }
+  if (label.length === 0 || copy.length === 0 || url.length === 0) return null;
+
+  return {
+    label,
+    copy,
+    url,
+    spans: Array.isArray(spans) && spans.length > 0 ? spans : [{ text: copy, link: true }],
+    // A slot or effect this copy does not know is drawn as none: a newer renderer's colour
+    // must degrade to the host's foreground, never to a string the host cannot parse.
+    style: isLineStyle(style) ? style : "default",
+    effect: isLineEffect(effect) ? effect : "none",
+    brand:
+      brand !== null && brand !== undefined && typeof brand.name === "string"
+        ? { name: brand.name, logo: typeof brand.logo === "string" ? brand.logo : null }
+        : null,
+  };
+}
+
+/**
+ * A configured command, split the way a shell would split it — quotes and all.
+ *
+ * `OBRIGADO_STATUSLINE_COMMAND` exists so a host can run a source checkout, and a checkout
+ * lives at a path. Splitting on spaces broke the moment that path contained one: `bun
+ * "/Users/Jane Doe/obrigado/cli.ts" statusline` became four arguments and the spawn failed
+ * silently. Double quotes, single quotes and backslash escapes are honoured; nothing else is
+ * interpreted — no variables, no globs, no operators — because this is a command, not a script.
+ */
+export function splitCommand(text: string): string[] {
+  const out: string[] = [];
+  let current = "";
+  let inToken = false;
+  let quote: '"' | "'" | null = null;
+
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index] ?? "";
+    if (quote !== null) {
+      if (character === quote) {
+        quote = null;
+      } else if (character === "\\" && quote === '"' && index + 1 < text.length) {
+        index += 1;
+        current += text[index] ?? "";
+      } else {
+        current += character;
+      }
+      continue;
+    }
+    if (character === '"' || character === "'") {
+      quote = character;
+      inToken = true;
+    } else if (character === "\\" && index + 1 < text.length) {
+      index += 1;
+      current += text[index] ?? "";
+      inToken = true;
+    } else if (/\s/u.test(character)) {
+      if (inToken) out.push(current);
+      current = "";
+      inToken = false;
+    } else {
+      current += character;
+      inToken = true;
+    }
+  }
+  if (inToken) out.push(current);
+  return out;
+}
+
+/**
+ * The argv a host spawns to get its line.
+ *
+ * `obrigado` from PATH is the installed case. An override — a setting, an environment
+ * variable — replaces the executable and its leading arguments and keeps everything after:
+ * the host names itself so the impression attributes to it, and asks for `--json` because it
+ * draws with its own primitives rather than printing an ANSI string.
+ */
+export function statuslineArgv(
+  agent: string,
+  override?: string | undefined,
+  options: { readonly json?: boolean } = {},
+): string[] {
+  const configured = override?.trim() ?? "";
+  const base = configured.length > 0 ? splitCommand(configured) : ["obrigado", "statusline"];
+  return [...base, "--agent", agent, ...(options.json === false ? [] : ["--json"])];
+}