gws-axi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jarvus Innovations
+
+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,91 @@
+# gws-axi
+
+Agent-ergonomic CLI for Google Workspace — Gmail, Calendar, Docs, Drive, and Slides behind a single command, built to the [AXI standard](https://axi.md): [TOON](https://toonformat.dev/)-formatted output, contextual next-step suggestions, idempotent mutations, and multi-account safety by default.
+
+Designed for use by AI agents. Every response is structured, every error names a specific fix, and write operations lock to the explicit account when multiple are authenticated — so two agents in parallel sessions can't silently touch the wrong mailbox.
+
+> **Status:** early release. **Calendar reads** (`calendar events`) are implemented with real TOON output. Other subcommands (`calendar get|create|update|…`, `gmail`, `docs`, `drive`, `slides`) are scaffolded but return `NOT_IMPLEMENTED`. Auth, doctor, and multi-account management are complete.
+
+## Requirements
+
+- Node.js ≥ 20
+- A Google account (personal or Workspace)
+- `gcloud` CLI (optional — speeds up initial setup, not required)
+
+## Install
+
+```bash
+npm install -g gws-axi
+```
+
+## First-run setup
+
+`gws-axi` uses a **bring-your-own OAuth client** model: you create your own Google Cloud project with OAuth credentials, and tokens live locally at `~/.config/gws-axi/`. This avoids verification/CASA overhead for public apps and keeps the blast radius of any token revocation scoped to you.
+
+The setup is progressive — run `gws-axi auth setup` repeatedly and each invocation walks you through the next step:
+
+```bash
+gws-axi auth setup   # start or continue — 7 steps, mostly automated
+gws-axi doctor       # check setup + live API health at any time
+```
+
+The CLI generates a styled, auto-refreshing HTML helper page at `~/.config/gws-axi/setup.html` with clickable Console deep-links — so you never copy long URLs from terminal to browser and you stay in the right browser profile throughout.
+
+Typical flow: set project → enable APIs → create OAuth client → download JSON → configure consent screen → add test users → authenticate. See the in-CLI guidance as you go; every step tells you exactly what to do next.
+
+## Usage
+
+Every subcommand supports `--help`. The bare `gws-axi` command prints current state, authenticated accounts, and top suggestions.
+
+```bash
+gws-axi                                  # home view
+gws-axi calendar events                  # list upcoming events
+gws-axi calendar events --query standup  # full-text search
+gws-axi calendar events --fields attendees,location
+gws-axi auth accounts                    # list authenticated Google accounts
+gws-axi auth login --account <email>     # add another account
+gws-axi doctor                           # full health check
+```
+
+### Multi-account with write protection
+
+gws-axi supports multiple Google accounts under one OAuth client. When two or more are authenticated, write operations require `--account <email>` explicitly — silent wrong-account mutations are impossible:
+
+```bash
+gws-axi calendar events                         # read: uses default account
+gws-axi calendar create --summary "..."         # write: ACCOUNT_REQUIRED error
+gws-axi calendar create --account chris@jarv.us --summary "..."  # OK
+```
+
+### Example output
+
+```
+account: chris@jarv.us
+count: 3
+range: 2026-04-20T14:00:00.000Z → 2026-04-27T14:00:00.000Z
+events[3]{id,summary,start,end,my_response}:
+  abc123,Team standup,2026-04-21T14:00:00-04:00,2026-04-21T14:15:00-04:00,accepted
+  def456,1:1 with Ari,2026-04-22T15:30:00-04:00,2026-04-22T16:00:00-04:00,accepted
+  ghi789,Board meeting,2026-04-25,2026-04-26,needsAction
+help[2]:
+  Run `gws-axi calendar get <id>` for full event details
+  Add `--fields attendees,location,status` to show more columns
+```
+
+## Design docs
+
+- [`docs/design.md`](https://github.com/JarvusInnovations/gws-axi/blob/main/docs/design.md) — architecture, auth model, doctor tiers, command surface
+- [`docs/shared-client-future.md`](https://github.com/JarvusInnovations/gws-axi/blob/main/docs/shared-client-future.md) — why BYO-only for v1, what a shared-client public distribution would involve
+
+## Known issues
+
+- **Testing-mode tokens expire every 7 days.** Google's OAuth policy. Re-run `gws-axi auth login --wait` when it happens. A future `gws-axi auth publish` helper will walk single-developer verification to eliminate this.
+- **Most service subcommands are not yet implemented.** Only `calendar events` does real work as of v0.1. The rest will follow — see the design doc for the order.
+
+## Contributing
+
+Issues and PRs welcome at [github.com/JarvusInnovations/gws-axi](https://github.com/JarvusInnovations/gws-axi).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/bin/gws-axi.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/gws-axi.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+main();
+//# sourceMappingURL=gws-axi.js.map

package/dist/bin/gws-axi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gws-axi.js","sourceRoot":"","sources":["../../bin/gws-axi.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAErC,IAAI,EAAE,CAAC"}

package/dist/src/auth/gcloud.d.ts

@@ -0,0 +1,21 @@
+export interface GcloudProject {
+    projectId: string;
+    name: string;
+    projectNumber: string;
+}
+export interface GcloudResult<T> {
+    ok: true;
+    value: T;
+}
+export interface GcloudError {
+    ok: false;
+    code: "NOT_INSTALLED" | "NOT_AUTHENTICATED" | "COMMAND_FAILED";
+    message: string;
+}
+export type GcloudOutcome<T> = GcloudResult<T> | GcloudError;
+export declare function isGcloudInstalled(): boolean;
+export declare function gcloudAccount(): GcloudOutcome<string>;
+export declare function listProjects(): GcloudOutcome<GcloudProject[]>;
+export declare function createProject(projectId: string, displayName: string): GcloudOutcome<GcloudProject>;
+export declare function enableApis(projectId: string, apis: string[]): GcloudOutcome<true>;
+export declare function listEnabledApis(projectId: string): GcloudOutcome<string[]>;

package/dist/src/auth/gcloud.js

@@ -0,0 +1,134 @@
+import { execFileSync } from "node:child_process";
+function runGcloud(args) {
+    try {
+        const out = execFileSync("gcloud", args, {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return { ok: true, value: out };
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT") {
+            return {
+                ok: false,
+                code: "NOT_INSTALLED",
+                message: "gcloud CLI is not installed",
+            };
+        }
+        const stderr = typeof e.stderr === "string"
+            ? e.stderr
+            : (e.stderr?.toString("utf-8") ?? "");
+        if (/you do not currently have an active account|please run.*auth login/i.test(stderr)) {
+            return {
+                ok: false,
+                code: "NOT_AUTHENTICATED",
+                message: "gcloud is not authenticated — run `gcloud auth login`",
+            };
+        }
+        return {
+            ok: false,
+            code: "COMMAND_FAILED",
+            message: stderr.split("\n").filter((l) => l.trim()).slice(-1)[0] ?? "gcloud command failed",
+        };
+    }
+}
+export function isGcloudInstalled() {
+    try {
+        execFileSync("gcloud", ["--version"], {
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function gcloudAccount() {
+    const result = runGcloud([
+        "auth",
+        "list",
+        "--filter=status:ACTIVE",
+        "--format=value(account)",
+    ]);
+    if (!result.ok)
+        return result;
+    const account = result.value.trim();
+    if (!account) {
+        return {
+            ok: false,
+            code: "NOT_AUTHENTICATED",
+            message: "No active gcloud account — run `gcloud auth login`",
+        };
+    }
+    return { ok: true, value: account };
+}
+export function listProjects() {
+    const result = runGcloud([
+        "projects",
+        "list",
+        "--format=json",
+        "--limit=100",
+    ]);
+    if (!result.ok)
+        return result;
+    try {
+        const parsed = JSON.parse(result.value);
+        return { ok: true, value: parsed };
+    }
+    catch {
+        return {
+            ok: false,
+            code: "COMMAND_FAILED",
+            message: "Failed to parse gcloud projects list output",
+        };
+    }
+}
+export function createProject(projectId, displayName) {
+    const result = runGcloud([
+        "projects",
+        "create",
+        projectId,
+        `--name=${displayName}`,
+        "--format=json",
+    ]);
+    if (!result.ok)
+        return result;
+    try {
+        const parsed = JSON.parse(result.value);
+        return { ok: true, value: parsed };
+    }
+    catch {
+        return {
+            ok: true,
+            value: { projectId, name: displayName, projectNumber: "" },
+        };
+    }
+}
+export function enableApis(projectId, apis) {
+    const result = runGcloud([
+        "services",
+        "enable",
+        ...apis,
+        `--project=${projectId}`,
+    ]);
+    if (!result.ok)
+        return result;
+    return { ok: true, value: true };
+}
+export function listEnabledApis(projectId) {
+    const result = runGcloud([
+        "services",
+        "list",
+        "--enabled",
+        `--project=${projectId}`,
+        "--format=value(config.name)",
+    ]);
+    if (!result.ok)
+        return result;
+    return {
+        ok: true,
+        value: result.value.split("\n").map((l) => l.trim()).filter(Boolean),
+    };
+}
+//# sourceMappingURL=gcloud.js.map

package/dist/src/auth/gcloud.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcloud.js","sourceRoot":"","sources":["../../../src/auth/gcloud.ts"],"names":[],"mappings":"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"}

package/dist/src/auth/loopback.d.ts

@@ -0,0 +1,50 @@
+import { type PendingAuth } from "./pending.js";
+import type { StepOutcome } from "./steps.js";
+export interface StoredTokens {
+    client_id: string;
+    access_token: string;
+    refresh_token?: string;
+    expiry_date: number;
+    scope: string;
+    token_type: string;
+    obtained_at: string;
+}
+export interface StoredProfile {
+    email: string;
+    verified_email: boolean;
+    name?: string;
+    picture?: string;
+    sub: string;
+    updated_at: string;
+}
+export interface PrepareOptions {
+    expectedAccount?: string;
+}
+export interface PrepareOutcome {
+    pending: PendingAuth;
+    htmlPath: string;
+    credentialsPresent: boolean;
+}
+/**
+ * Phase 1: generate the auth URL, reserve a port, persist pending state,
+ * write setup.html with the authenticate button. Returns immediately so the
+ * agent can relay instructions to the user BEFORE any process blocks on a
+ * callback. Call `awaitPendingAuth` after instructing the user.
+ */
+export declare function preparePendingAuth(options?: PrepareOptions): Promise<PrepareOutcome | {
+    error: string;
+    code: string;
+}>;
+/**
+ * Phase 2: read pending state, start the callback server, block until the
+ * user authenticates (or timeout). Runs the token exchange, fetches the
+ * userinfo to identify the account, writes tokens + profile, updates
+ * default account if first, regenerates setup.html without the banner.
+ */
+export declare function awaitPendingAuth(): Promise<StepOutcome>;
+/**
+ * Helper for callers (like `auth setup`) that want to expose the prepared
+ * instructions to the user/agent as a StepOutcome. Does NOT block — just
+ * wraps preparePendingAuth into the StepOutcome shape.
+ */
+export declare function advanceTokensObtained(options?: PrepareOptions): Promise<StepOutcome>;