@objectsws/s-portal 0.1.0

package/MANUAL_TEST.md

@@ -0,0 +1,99 @@
+# Manual test path — `@objects/s-portal` connect / discard
+
+Use this checklist after portal APIs and the CLI package are built.
+
+## Prerequisites
+
+- Apps Portal running locally or on a reachable host
+- A Shopify Remix app checkout (or any folder with `shopify.app.toml` + `app/routes`)
+- Node 18+
+
+## Connect
+
+1. **Rotate credentials** on the app detail page in the portal  
+   - Open the app → **Generate credentials** / **Rotate credentials**  
+   - Copy **Client Id** and **Client Secret** (secret shown once)
+
+2. **Build the CLI** (from this monorepo, until published to npm)
+
+   ```bash
+   cd packages/s-portal-cli
+   npm install
+   npm run build
+   ```
+
+3. **Run connect** from the Shopify Remix app root
+
+   ```bash
+   node /path/to/apps-portal/packages/s-portal-cli/dist/index.js connect \
+     --portal-url http://localhost:5173 \
+     --client-id portal-your-handle \
+     --client-secret '…' \
+     --remote-base-url https://your-tunnel.example.com \
+     --yes
+   ```
+
+   Or interactive: `node …/dist/index.js` (omit flags; default command is `connect`).
+
+4. **Confirm scaffold**
+   - `portal/client.server.ts`, `heartbeat.server.ts`, `notify.server.ts`, `README.md`
+   - `app/routes/healthz.ts`, `app/routes/api.portal-sync.tsx`
+   - `.env` contains `PORTAL_*` and `HEARTBEAT_INTERVAL_MS`
+   - `app/entry.server.*` has the scaffolded `startHeartbeatLoop()` markers
+
+5. **Verify in portal UI**
+   - App detail → Remote Base URL matches what you entered
+   - Active Check URL = `{remoteBaseUrl}/healthz`
+   - Sync connection enabled
+   - **Verify connection** (token exchange) once the remote app is deployed/reachable
+   - Optional: **Manual sync** after implementing the merchants query (`id` + `shop` required)
+
+6. **Verify active check**
+   - Deploy or tunnel so `{remoteBaseUrl}/healthz` returns 200 JSON
+   - Monitor settings → run **Manual check** (or wait for scheduled probe)
+   - Expect status **up** when healthz is healthy
+
+7. **Re-run idempotency**
+   - Run connect again with the same Remote Base URL  
+   - Expect existing files skipped (or overwrite with `--force`) and connection updated
+
+## Discard
+
+8. **Run discard** from the same Shopify app root
+
+   ```bash
+   node /path/to/apps-portal/packages/s-portal-cli/dist/index.js discard --yes
+   ```
+
+   Or local-only (no portal API):
+
+   ```bash
+   node …/dist/index.js discard --yes --local-only
+   ```
+
+9. **Confirm local cleanup**
+   - Owned scaffold files removed (`portal/*`, `healthz`, `api.portal-sync`)
+   - Heartbeat markers removed from `entry.server` (or a note if you rewrote them)
+   - `PORTAL_*` / `HEARTBEAT_INTERVAL_MS` stripped from `.env`; other keys untouched
+   - Modified scaffold files skipped unless `--force`
+
+10. **Confirm soft disconnect in portal UI**
+    - Remote Base URL cleared / sync disabled
+    - Active check disabled / target cleared
+    - **Client Id still present**; secret still configured (no rotation)
+    - Reconnect works by running `connect` again with the same credentials
+
+## API smoke (optional)
+
+With credentials:
+
+```bash
+# whoami — HMAC over empty body
+# connect — HMAC over raw JSON body
+# disconnect — HMAC over "{}"
+# See packages/s-portal-cli/src/portalApi.ts for header scheme
+```
+
+Expect `GET /api/cli/whoami` → `{ ok, app: { id, name, handle }, … }`  
+Expect `POST /api/cli/connect` → `{ ok, syncBaseUrl, activeCheckUrl, verified, portal: { heartbeatUrl, webhookUrl } }`  
+Expect `POST /api/cli/disconnect` → `{ ok, appId, disconnected: true }`

package/README.md

@@ -0,0 +1,124 @@
+# `@objects/s-portal`
+
+CLI that scaffolds Apps Portal sync into a Shopify Remix app and registers your **Remote Base URL** with the portal sync engine.
+
+## Prerequisites
+
+1. Create/link the app in **Apps Portal**.
+2. On the app detail page, click **Generate credentials** and copy **Client Id** + **Client Secret**.
+3. Have your deployed Shopify app public origin ready (Remote Base URL).
+
+## Usage
+
+From your Shopify Remix app root:
+
+```bash
+npx @objects/s-portal
+# same as:
+npx @objects/s-portal connect
+```
+
+Non-interactive:
+
+```bash
+npx @objects/s-portal connect \
+  --portal-url https://your-portal.example.com \
+  --client-id portal-my-app \
+  --client-secret '…' \
+  --remote-base-url https://my-shopify-app.example.com \
+  --yes
+```
+
+Scaffold only (no portal API calls):
+
+```bash
+npx @objects/s-portal connect --scaffold-only
+```
+
+### Discard (tear down)
+
+Removes CLI-scaffolded files, strips `PORTAL_*` / `HEARTBEAT_INTERVAL_MS` from `.env`, unpatches the heartbeat markers in `entry.server`, and **soft-disconnects** on the portal (clears Remote Base URL + disables sync/active check; **keeps** Client Id/Secret).
+
+```bash
+npx @objects/s-portal discard
+```
+
+Non-interactive:
+
+```bash
+npx @objects/s-portal discard --yes
+# or skip portal API:
+npx @objects/s-portal discard --yes --local-only
+# delete scaffold files even if you edited them:
+npx @objects/s-portal discard --yes --force
+```
+
+Credentials for disconnect are resolved from flags → `.env` → prompts. If missing, local cleanup still runs and portal disconnect is skipped with a warning.
+
+## Flow
+
+**Connect**
+
+1. Detect Shopify Remix app
+2. Scaffold `portal/` helpers + `healthz` + `api.portal-sync` routes
+3. Prompt Portal URL, Client Id, Client Secret
+4. Confirm app (`GET /api/cli/whoami`)
+5. Prompt Remote Base URL → Active Check = `{base}/healthz`
+6. `POST /api/cli/connect` → write `.env` → **Connected**
+
+**Discard**
+
+1. Confirm (unless `--yes`)
+2. `POST /api/cli/disconnect` (unless `--local-only` / missing creds)
+3. Remove owned scaffold files + unpatch entry.server + strip env → **Discarded**
+
+## Publish to npm
+
+Publish from this package directory (not the monorepo root).
+
+### One-time setup
+
+1. Create or join the npm org **`objects`** (package name is `@objects/s-portal`).
+2. `npm login` with an account that can publish under `@objects`.
+3. Confirm: `npm access list packages @objects` (or npm Dashboard → Orgs).
+
+### Every release
+
+```bash
+cd packages/s-portal-cli
+npm install
+npm run build
+npm pack --dry-run   # should list dist/, templates/, README.md, MANUAL_TEST.md
+npm version patch    # bump from 0.1.0 on later releases
+npm publish --access public
+```
+
+Scoped packages need `--access public` for free public installs.
+
+### Use in any Shopify app folder
+
+```bash
+cd /path/to/other-shopify-app
+npx @objects/s-portal@latest
+npx @objects/s-portal discard --yes
+```
+
+Until published, run the built binary directly:
+
+```bash
+node /path/to/apps-portal/packages/s-portal-cli/dist/index.js connect
+node /path/to/apps-portal/packages/s-portal-cli/dist/index.js discard --yes --local-only
+```
+
+## Local development (this monorepo)
+
+```bash
+cd packages/s-portal-cli
+npm install
+npm run build
+node dist/index.js --help
+```
+
+## Manual test checklist
+
+See [MANUAL_TEST.md](./MANUAL_TEST.md) — rotate credentials → CLI connect → verify sync + active check → discard.

package/dist/detect.d.ts

@@ -0,0 +1,11 @@
+export type DetectResult = {
+    root: string;
+    hasShopifyToml: boolean;
+    hasAppRoutes: boolean;
+    packageName: string | null;
+};
+/**
+ * Detect a Shopify Remix / React Router app from the current working directory
+ * (or nearest parent with shopify.app.toml / app/routes).
+ */
+export declare function detectShopifyApp(cwd?: string): DetectResult;

package/dist/detect.js

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Detect a Shopify Remix / React Router app from the current working directory
+ * (or nearest parent with shopify.app.toml / app/routes).
+ */
+export function detectShopifyApp(cwd = process.cwd()) {
+    let dir = path.resolve(cwd);
+    const rootStop = path.parse(dir).root;
+    while (true) {
+        const toml = path.join(dir, "shopify.app.toml");
+        const routes = path.join(dir, "app", "routes");
+        const pkgPath = path.join(dir, "package.json");
+        const hasShopifyToml = fs.existsSync(toml);
+        const hasAppRoutes = fs.existsSync(routes);
+        if (hasShopifyToml || hasAppRoutes) {
+            let packageName = null;
+            if (fs.existsSync(pkgPath)) {
+                try {
+                    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+                    packageName = pkg.name ?? null;
+                    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+                    const looksShopify = hasShopifyToml ||
+                        Boolean(deps["@shopify/shopify-app-remix"]) ||
+                        Boolean(deps["@shopify/shopify-app-react-router"]);
+                    if (!looksShopify && !hasShopifyToml) {
+                        // Keep walking if this is only a generic app/routes folder
+                    }
+                    else {
+                        return { root: dir, hasShopifyToml, hasAppRoutes, packageName };
+                    }
+                    if (hasShopifyToml || hasAppRoutes) {
+                        return { root: dir, hasShopifyToml, hasAppRoutes, packageName };
+                    }
+                }
+                catch {
+                    return { root: dir, hasShopifyToml, hasAppRoutes, packageName: null };
+                }
+            }
+            return { root: dir, hasShopifyToml, hasAppRoutes, packageName };
+        }
+        if (dir === rootStop)
+            break;
+        dir = path.dirname(dir);
+    }
+    throw new Error("Could not detect a Shopify Remix app. Run this from your app root (look for shopify.app.toml or app/routes).");
+}

package/dist/discard.d.ts

@@ -0,0 +1,24 @@
+/** Files owned by the CLI scaffold (rel path → template name). */
+export declare const SCAFFOLD_OWNED_FILES: Array<{
+    rel: string;
+    template: string;
+}>;
+export declare const PORTAL_ENV_KEYS: readonly ["PORTAL_HEARTBEAT_URL", "PORTAL_WEBHOOK_URL", "PORTAL_CLIENT_ID", "PORTAL_CLIENT_SECRET", "HEARTBEAT_INTERVAL_MS"];
+export type DiscardLocalResult = {
+    removed: string[];
+    skipped: string[];
+    entryHint: string | null;
+    envStripped: string[];
+};
+/**
+ * Remove CLI-owned scaffold files, unpatch entry.server markers, strip portal env keys.
+ */
+export declare function discardLocalFiles(appRoot: string, opts?: {
+    force?: boolean;
+}): DiscardLocalResult;
+export declare function stripEnvKeys(appRoot: string, keys: string[]): {
+    path: string;
+    stripped: string[];
+};
+/** Read selected keys from .env (no secret logging by callers). */
+export declare function readEnvKeys(appRoot: string, keys: string[]): Record<string, string>;

package/dist/discard.js

@@ -0,0 +1,148 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readTemplate } from "./utils.js";
+/** Files owned by the CLI scaffold (rel path → template name). */
+export const SCAFFOLD_OWNED_FILES = [
+    { rel: "portal/client.server.ts", template: "portal.client.server.ts" },
+    { rel: "portal/heartbeat.server.ts", template: "portal.heartbeat.server.ts" },
+    { rel: "portal/notify.server.ts", template: "portal.notify.server.ts" },
+    { rel: "portal/README.md", template: "portal.README.md" },
+    { rel: "app/routes/healthz.ts", template: "routes.healthz.ts" },
+    { rel: "app/routes/api.portal-sync.tsx", template: "routes.api.portal-sync.tsx" },
+];
+export const PORTAL_ENV_KEYS = [
+    "PORTAL_HEARTBEAT_URL",
+    "PORTAL_WEBHOOK_URL",
+    "PORTAL_CLIENT_ID",
+    "PORTAL_CLIENT_SECRET",
+    "HEARTBEAT_INTERVAL_MS",
+];
+const ENTRY_CANDIDATES = [
+    "app/entry.server.tsx",
+    "app/entry.server.ts",
+    "app/entry.server.jsx",
+];
+const HEARTBEAT_IMPORT_RE = /^import\s+\{\s*startHeartbeatLoop\s*\}\s+from\s+["']\.\.\/portal\/heartbeat\.server["'];?\s*\n?/m;
+const HEARTBEAT_CALL_RE = /\n*\/\/ Apps Portal heartbeat \(scaffolded by @objects\/s-portal\)\s*\n\s*startHeartbeatLoop\(\);\s*/;
+function normalizeContent(s) {
+    return s.replace(/\r\n/g, "\n").trimEnd() + "\n";
+}
+/**
+ * Remove CLI-owned scaffold files, unpatch entry.server markers, strip portal env keys.
+ */
+export function discardLocalFiles(appRoot, opts = {}) {
+    const force = opts.force ?? false;
+    const removed = [];
+    const skipped = [];
+    for (const file of SCAFFOLD_OWNED_FILES) {
+        const abs = path.join(appRoot, file.rel);
+        if (!fs.existsSync(abs)) {
+            skipped.push(`${file.rel} (missing)`);
+            continue;
+        }
+        if (!force) {
+            const onDisk = normalizeContent(fs.readFileSync(abs, "utf8"));
+            const template = normalizeContent(readTemplate(file.template));
+            if (onDisk !== template) {
+                skipped.push(`${file.rel} (modified — use --force to delete)`);
+                continue;
+            }
+        }
+        fs.unlinkSync(abs);
+        removed.push(file.rel);
+    }
+    // Remove empty portal/ directory
+    const portalDir = path.join(appRoot, "portal");
+    if (fs.existsSync(portalDir)) {
+        try {
+            const remaining = fs.readdirSync(portalDir);
+            if (remaining.length === 0) {
+                fs.rmdirSync(portalDir);
+                removed.push("portal/ (empty dir)");
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    let entryHint = null;
+    let entryTouched = false;
+    for (const rel of ENTRY_CANDIDATES) {
+        const abs = path.join(appRoot, rel);
+        if (!fs.existsSync(abs))
+            continue;
+        const before = fs.readFileSync(abs, "utf8");
+        if (!before.includes("startHeartbeatLoop") &&
+            !before.includes("portal/heartbeat.server")) {
+            continue;
+        }
+        let after = before;
+        const hadImport = HEARTBEAT_IMPORT_RE.test(after);
+        const hadCall = HEARTBEAT_CALL_RE.test(after);
+        after = after.replace(HEARTBEAT_IMPORT_RE, "");
+        after = after.replace(HEARTBEAT_CALL_RE, "\n");
+        after = after.replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+        if (after !== before && (hadImport || hadCall)) {
+            fs.writeFileSync(abs, after, "utf8");
+            removed.push(`${rel} (heartbeat unpatched)`);
+            entryTouched = true;
+        }
+        else if (before.includes("startHeartbeatLoop")) {
+            entryHint = `${rel} still references startHeartbeatLoop — remove manually if needed.`;
+        }
+        break;
+    }
+    if (!entryTouched && !entryHint) {
+        entryHint = null;
+    }
+    const env = stripEnvKeys(appRoot, [...PORTAL_ENV_KEYS]);
+    return {
+        removed,
+        skipped,
+        entryHint,
+        envStripped: env.stripped,
+    };
+}
+export function stripEnvKeys(appRoot, keys) {
+    const envPath = path.join(appRoot, ".env");
+    if (!fs.existsSync(envPath)) {
+        return { path: envPath, stripped: [] };
+    }
+    const keySet = new Set(keys);
+    const lines = fs.readFileSync(envPath, "utf8").split(/\r?\n/);
+    const stripped = [];
+    const kept = [];
+    for (const line of lines) {
+        const m = line.match(/^([A-Z0-9_]+)=/);
+        if (m && keySet.has(m[1])) {
+            stripped.push(m[1]);
+            continue;
+        }
+        kept.push(line);
+    }
+    if (stripped.length) {
+        const out = kept.join("\n").replace(/\n+$/, "\n");
+        fs.writeFileSync(envPath, out || "", "utf8");
+    }
+    return { path: envPath, stripped };
+}
+/** Read selected keys from .env (no secret logging by callers). */
+export function readEnvKeys(appRoot, keys) {
+    const envPath = path.join(appRoot, ".env");
+    const out = {};
+    if (!fs.existsSync(envPath))
+        return out;
+    const keySet = new Set(keys);
+    for (const line of fs.readFileSync(envPath, "utf8").split(/\r?\n/)) {
+        const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
+        if (!m || !keySet.has(m[1]))
+            continue;
+        let val = m[2].trim();
+        if ((val.startsWith('"') && val.endsWith('"')) ||
+            (val.startsWith("'") && val.endsWith("'"))) {
+            val = val.slice(1, -1);
+        }
+        out[m[1]] = val;
+    }
+    return out;
+}

package/dist/index.d.ts

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