forkit-connect 0.1.0

package/QUICKSTART.md

@@ -0,0 +1,55 @@
+# Forkit Connect Quickstart
+
+## Ubuntu Install
+
+```bash
+cd integrations/connect
+pnpm run install:ubuntu
+export PATH="$HOME/.local/bin:$PATH"
+forkit-connect --help
+```
+
+On apt-based Linux, the installer now offers to install `libsecret-tools` so `forkit-connect login` can persist the device session securely between runs.
+
+If you want the command available in new shells too, add this to `~/.bashrc`:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+## Recommended First Run
+
+```bash
+forkit-connect init
+forkit-connect login
+forkit-connect scan
+forkit-connect inbox
+forkit-connect changes
+forkit-connect status
+forkit-connect start
+```
+
+## What Each Step Does
+
+- `init` creates local Connect identity and privacy posture metadata.
+- `login` completes the device-login flow against Forkit.dev.
+- `scan` detects supported local runtimes and AI models.
+- `inbox` shows what is ready to connect, what needs confirmation, and what is already connected.
+- `changes` shows the local evidence trail, runtime signal history, and anything still waiting to sync.
+- `status` summarizes readiness, daemon state, discovery counts, and next recommended action.
+- `start` launches the daemon loop for continued local discovery and sync preparation.
+
+## Useful Next Commands
+
+- `forkit-connect connect <modelNameOrDiscoveryHash>` — prepare or sync a Passport draft for a detected model
+- `forkit-connect daemon status` — inspect daemon state
+- `forkit-connect pulse status` — inspect best-effort local runtime telemetry
+- `forkit-connect agent review` — inspect detected local AI agents
+- `forkit-connect update-check` — inspect release metadata without enabling auto-update
+
+## Notes
+
+- Resource usage shown by Connect is heuristic runtime-health telemetry, not billing.
+- Normal users do not need to expose or manage backend API keys.
+- Website governance remains the authority for workspace, project, and Passport control.
+- For pre-publish validation, generate a tarball with `npm pack` and run `pnpm run smoke:package`.

package/README.md

@@ -0,0 +1,96 @@
+# Forkit Connect
+
+Forkit Connect is the local engine for discovering AI runtimes, reviewing what is running on-device, and preparing metadata-only Passport and lifecycle handoff into Forkit.dev.
+
+## Install Surface
+
+- Package name: `@forkit/connect`
+- Public binary: `forkit-connect`
+- Intended bootstrap: `npx forkit-connect ...` once published
+- Current pre-publish workflow: install from a local tarball generated with `npm pack`
+- Current Ubuntu shortcut: `pnpm run install:ubuntu` installs into user space without `sudo`
+
+## Ubuntu Install
+
+Requirements:
+
+- Node.js `20+`
+- `npm`
+- `pnpm` for local packaging from this repo
+- On Linux, `libsecret-tools` is recommended so Forkit Connect can store login credentials in Secret Service
+
+From `integrations/connect`:
+
+```bash
+pnpm run install:ubuntu
+export PATH="$HOME/.local/bin:$PATH"
+forkit-connect --help
+forkit-connect status
+```
+
+The installer:
+
+- builds and packs the current Connect package
+- installs it into `~/.local/share/forkit-connect`
+- links `forkit-connect` into `~/.local/bin`
+- offers to install `libsecret-tools` on apt-based Linux so login persistence works without a separate manual step
+- avoids `sudo` and does not require the full monorepo at runtime after install
+
+If `libsecret-tools` is not present, read-only commands still work, but stored login persistence on Linux will stay limited until Secret Service tooling is installed.
+
+If `~/.local/bin` is already on your `PATH`, the command is immediately accessible.
+
+## Public Commands
+
+- `forkit-connect init` — initialize local Connect identity and privacy posture
+- `forkit-connect login` — link this device to Forkit.dev with the device flow
+- `forkit-connect scan` — discover local runtimes and AI models
+- `forkit-connect inbox` — review the Smart Registration Inbox
+- `forkit-connect status` — show public Connect readiness status
+- `forkit-connect changes` — view collected local evidence, runtime signal history, and pending sync items
+- `forkit-connect start` — start the local daemon loop
+
+## Advanced Commands
+
+Advanced flows remain available under the same binary, including `connect`, `review`, `daemon`, `config`, `pulse`, `c2`, `train`, `agent`, and notification utilities.
+
+## Privacy and Security Posture
+
+- Session credentials are stored outside `state.v1.json`.
+- Backend-bound endpoint metadata is sanitized before upload.
+- Connect does not require normal users to manage backend API keys.
+- Local runtime telemetry is best-effort health data, not billing or exact cost accounting.
+- Website and backend governance remain authoritative for registration and C2 decisions.
+- Auto-update is not enabled as a package-install workflow.
+
+## Local Tarball Flow
+
+From `integrations/connect`:
+
+```bash
+pnpm run prepack
+npm pack
+```
+
+Then install the generated tarball into a clean directory:
+
+```bash
+mkdir -p /tmp/forkit-connect-smoke
+cd /tmp/forkit-connect-smoke
+npm init -y
+npm install /absolute/path/to/forkit-connect-0.1.0.tgz
+npx forkit-connect --help
+npx forkit-connect status
+npx forkit-connect inbox
+npx forkit-connect init
+```
+
+For a user-space Ubuntu install that creates a stable command path, prefer `pnpm run install:ubuntu`.
+
+## Development Notes
+
+- Build config: `tsconfig.build.json`
+- Package smoke script: `pnpm run smoke:package`
+- Dist pruning removes compiled tests and source maps before packaging
+
+See `QUICKSTART.md` for the recommended onboarding sequence.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map