piezas 0.2.0

package/README.md

@@ -0,0 +1,309 @@
+# piezas
+
+Set up [Piezas](https://piezas.ai) in your project with one command. Installs the SDK and configures your AI coding agent (Claude Code, Cursor, Codex, Windsurf) to use Piezas as your backend.
+
+## Quick Start
+
+```bash
+npx piezas init
+```
+
+Then generate a spec before coding:
+
+```bash
+# Claude Code
+/piezas-spec "booking app for a small consulting team"
+
+# Cursor, Codex, Windsurf, or other agents
+/piezas-spec booking app for a small consulting team
+```
+
+Or create and initialize a new folder:
+
+```bash
+npx piezas init my-app
+```
+
+Choose a deployment mode when you already know it:
+
+```bash
+npx piezas init --mode next-bff    # "frontend with a small server layer" — any framework
+```
+
+Piezas is framework-agnostic: the platform is plain HTTPS/OpenAPI, and the
+generated agent instructions tell your coding agent to honor *your* framework
+choice (Vite+Express, Remix, SvelteKit, Next.js, or a non-JS stack) rather
+than prescribing one. Mode names are historical labels, not requirements.
+
+(`--mode static` also exists for server-less static hosting, but is **not
+recommended yet**: static apps must rely on public guest tokens, and per-token
+permission enforcement hasn't shipped platform-wide. Prefer a server-capable
+mode like `next-bff` until it does.)
+
+For server-capable apps, add an SDK-backed MCP route for agent tool access:
+
+```bash
+npx piezas init --mode next-bff --mcp
+```
+
+Add recipe guidance for common product shapes:
+
+```bash
+npx piezas init --recipe booking-site
+npx piezas init --recipe crm-project-finance --recipe client-services-os
+```
+
+Bring your API key from the dashboard (any one of these):
+
+```bash
+npx piezas init --key sk_live_xxx          # pass it directly
+npx piezas init                            # paste it at the prompt (TTY only)
+npx piezas init --wait                     # watch the folder for the dashboard's downloaded .env
+npx piezas init --wait --wait-timeout 600  # ... for up to 10 minutes
+```
+
+`init` looks for a key in this order: `--key` (replaces an existing `.env`
+value — passing it explicitly means you want it set), an existing
+`PIEZAS_API_KEY` in the project's `.env` (kept as-is), `PIEZAS_API_KEY` in
+your environment (never overrides an already-configured project), an
+interactive paste prompt, then `--wait` (polls every 2s for a dropped-in
+`.env`, `.env.download`, or `env.txt`; the drop file is removed once the key
+is moved into `.env`). A missing key is not an error — the project is still
+scaffolded and the summary tells you where to put the key.
+
+## Sign In From the Terminal
+
+No dashboard needed — sign in once, then let `init` create the app and key:
+
+```bash
+npx piezas login    # prints a short code and opens your browser to approve it
+npx piezas whoami   # shows the signed-in tenant and email (exit 1 when logged out)
+npx piezas logout   # removes the saved session
+```
+
+`login` starts a device-code sign-in: it shows a short code, opens
+`app.piezas.ai/device` in your browser (the URL is always printed in case the
+browser does not open), and waits for you to approve the code — sign-up works
+on the same page. The session is saved to `~/.piezas/credentials.json`
+(permissions `600`; override the directory with `PIEZAS_HOME`). The API base
+is `https://api.piezas.ai` by default; override with `--api-base <url>` or
+`PIEZAS_API_BASE`. All three commands support `--json`.
+
+Once signed in, `init` can finish the whole setup from the terminal. When no
+API key is found by the intake order above, `init` offers to create an app
+named after your folder (or `--app <name>`) and mint a live key bound to it,
+writing the key straight into `.env`:
+
+```bash
+npx piezas login
+npx piezas init --from-login          # non-interactive: always use the saved login
+npx piezas init                       # interactive: you'll be offered the same thing
+```
+
+If the app name already exists in your account, the existing app is reused
+and a fresh key is minted for it. If the saved session has expired, `init`
+says so and continues without a key — run `npx piezas login` again. Without a
+saved session, `init` behaves exactly as before.
+
+Agent-friendly flags: `--yes` never prompts, `--app <name>` records the app
+name in `piezas.manifest.json`, `--from-login` mints a key with the saved
+`piezas login` session when none is found, and `--json` prints a
+machine-readable summary (`apiKey`, `apiKeySource`, `envPath`,
+`gitignoreUpdated`, `cursorRulesPath`, `appName`) on stdout. Exit codes: `0`
+success (even without a key), `1` failure, `2` usage error.
+
+This will:
+
+- Install `@piezas/sdk`
+- Create `package.json` when one does not exist
+- Create `piezas.manifest.json` as the app/Piezas ownership and deployment-mode source of truth (records `appName` and `apiBaseUrl`)
+- Write `PIEZAS_API_KEY` into `.env` and make sure `.gitignore` covers `.env` (existing patterns like `*.env` are respected)
+- Add recipe ownership and setup-order guidance when `--recipe` is provided
+- Optionally scaffold `app/api/piezas/mcp/route.ts` when `--mcp` is used with a server-capable mode
+- Add Piezas instructions to `CLAUDE.md`, `.cursor/rules/piezas.mdc`, `.cursorrules`, `AGENTS.md`, and `.windsurfrules`
+- Create a `.claude/commands/piezas.md` slash command for Claude Code
+- Create `.claude/commands/piezas-spec.md` and `.piezas/spec-builder.md` for spec-first app generation
+
+The generated instructions are an operating manual for AI coding agents. They
+cover the init -> spec -> code workflow, the Piezas/app ownership boundary,
+static vs server-runtime deployment mode, server-side API key handling, SDK
+usage, live OpenAPI specs, integration OAuth rules, app-scoped connector
+configuration, public sessions, durable access logs, durable/sync jobs, document
+extraction, e-signature state, accounting posting helpers, search/import/export,
+reconciliation helpers, thin server adapters, SDK-backed MCP routes, and common
+CRM, public intake, booking, finance, and project-tracker patterns.
+
+## Spec-First Workflow
+
+Use this sequence for broad product requests:
+
+1. Run `npx piezas init`.
+2. Run `/piezas-spec [idea]` in Claude Code, or ask Cursor/Codex/Windsurf for `/piezas-spec [idea]` or "Piezas spec mode".
+3. The agent interviews the user one question at a time and writes `SPEC.md` or `specs/`.
+4. Ask the agent to code from the finalized spec.
+5. Run `npx piezas doctor` before deployment.
+
+Spec mode does not implement code. It creates the buildable product/architecture
+spec first so the coding agent has a concrete target and a Piezas service map.
+
+## Guardrail Scan
+
+After an AI coding agent generates or edits the app, run:
+
+```bash
+npx piezas doctor
+```
+
+`doctor` checks for architecture mistakes that sparse prompts often miss:
+
+- `PIEZAS_API_KEY` exposed to browser/client code
+- static deployments that accidentally contain server routes or server actions
+- admin tokens/passwords passed through URL query params
+- public booking flows that trust hidden time fields without server-side slot revalidation
+- local database dependencies that may duplicate Piezas-owned business records
+- OAuth token storage in app code
+- dynamic route params that appear unused
+- hardcoded integration action IDs without connector action discovery
+- coverage configs that exclude app/API/server-action code
+
+Use strict mode in CI when you want warnings to fail:
+
+```bash
+npx piezas doctor --strict
+```
+
+Print machine-readable output:
+
+```bash
+npx piezas doctor --json
+```
+
+## What is Piezas?
+
+Piezas by [Softmax Data](https://softmaxdata.com) is a suite of backend services so you don't have to build your own. It includes:
+
+- **Entity Records** — Store any business data (contacts, products, cases)
+- **Pipeline Engine** — Kanban boards and stage workflows
+- **Task Engine** — Task management with priorities and due dates
+- **Notifications** — Email and in-app notifications
+- **Calendar** — Event scheduling
+- **Messaging** — Sequences and campaigns
+- **Workflow** — Automation and triggers
+- **Durable Jobs** — Deferred work, retries, stale-lock recovery, reminders, imports, and sync state
+- **Forms** — Form builder and submissions
+- **Documents** — File storage and management
+- **Document Workflows** — Extraction jobs and signature request state
+- **Reporting** — Analytics and dashboards
+- **Pricing** — Product and pricing management
+- **Discussion** — Threaded conversations
+- **Knowledge Base** — Document ingestion, semantic search, and AI Q&A
+- **Integrations** — OAuth connections, scoped grants, and provider actions
+- **Connector Pack** — Google Calendar, Gmail, Google Drive, Zoom, HubSpot, DocuSign, QuickBooks, and AWS Textract-compatible proxy actions
+- **Admin/access** — Tenant users, invite-only signup, app registry, public sessions, durable access logs, and audit events
+- **MCP-ready SDK surface** — Server apps can expose Piezas entity, pipeline, and task tools to approved agents through `piezasMcp`
+
+## App-Scoped Integrations
+
+For products with multiple generated apps, domains, OAuth callback URLs, or provider permission sets, create one Piezas tenant app per app/use case. The tenant app stores allowed origins, redirect URIs, auth policy metadata, and connector/purpose policy. Integrations can then store provider client credentials with `appId` and `purpose`, and OAuth calls pass the same `appId`/`purpose`.
+
+That means a booking app that needs Google Calendar and Zoom can stay separate from an internal app that only needs Google identity or Gmail-backed sending. Generated apps should store only the Piezas tenant app slug/id, connection IDs, grant IDs, and business record references.
+
+## MCP Route
+
+`@piezas/sdk` includes `piezasMcp`, so there is no separate public MCP package to install. For Next.js/server-runtime apps:
+
+```bash
+npx piezas init --mode next-bff --mcp
+```
+
+This creates `app/api/piezas/mcp/route.ts`, wired to `piezasMcp` from `@piezas/sdk`. The generated route rejects anonymous requests until the app supplies auth plus tenant/user context. Replace the placeholder guard with your real session check before exposing it to users or agents. Static deployments should not host this route; use a separate server adapter if agent tool access is needed.
+
+## Next Steps
+
+1. Get an API key at [app.piezas.ai](https://app.piezas.ai)
+2. Add `PIEZAS_API_KEY=sk_live_xxx` to your server-side environment
+3. Run `/piezas-spec [idea]` or ask for Piezas spec mode
+4. Tell your AI agent to code from `SPEC.md` or `specs/`
+5. Run `npx piezas doctor` before deployment
+
+## SDK Usage
+
+```typescript
+import { Piezas } from '@piezas/sdk';
+
+const piezas = new Piezas({
+  apiKey: process.env.PIEZAS_API_KEY,
+  entitiesUrl: 'https://api.piezas.ai/entities',
+  pipelineUrl: 'https://api.piezas.ai/pipeline',
+  tasksUrl: 'https://api.piezas.ai/tasks',
+  notificationsUrl: 'https://api.piezas.ai/notify',
+  integrationsUrl: 'https://api.piezas.ai/integrations',
+  calendarUrl: 'https://api.piezas.ai/calendar',
+  workflowUrl: 'https://api.piezas.ai/workflow',
+  messagingUrl: 'https://api.piezas.ai/messaging',
+  formsUrl: 'https://api.piezas.ai/forms',
+  documentsUrl: 'https://api.piezas.ai/documents',
+  reportingUrl: 'https://api.piezas.ai/reporting',
+  pricingUrl: 'https://api.piezas.ai/pricing',
+  discussionUrl: 'https://api.piezas.ai/discussion',
+  knowledgeBaseUrl: 'https://api.piezas.ai/knowledge-base',
+  adminUrl: 'https://api.piezas.ai/admin',
+});
+
+// Define entity types (idempotent — safe to re-run)
+await piezas.defineEntities({
+  contact: {
+    fields: {
+      email: { type: 'email', required: true },
+      status: { type: 'select', options: ['active', 'lead'] },
+    },
+  },
+});
+
+// CRUD
+const record = await piezas.contacts.create({ title: 'Jane', data: { email: 'jane@example.com' } });
+const list = await piezas.contacts.list({ limit: 50 });
+const search = await piezas.contacts.search({ q: 'jane' });
+const slots = await piezas.calendar.getAvailableSlots({
+  calendarId: 'calendar-id',
+  dateFrom: '2026-05-25T00:00:00Z',
+  dateTo: '2026-05-26T00:00:00Z',
+});
+await piezas.workflow.enqueueJob({ type: 'followup.reminder', payload: { recordId: record.id } });
+await piezas.workflow.enqueueSyncJob({ connector: 'gmail', resource: 'messages', direction: 'pull' });
+await piezas.documents.createExtractionJob({
+  documentId: 'document-id',
+  provider: 'aws_textract',
+  requestedFields: ['invoice_number', 'total'],
+});
+await piezas.documents.createSignatureRequest({
+  title: 'MSA',
+  documentId: 'document-id',
+  provider: 'docusign',
+  signers: [{ name: 'Jane Client', email: 'jane@example.com' }],
+});
+await piezas.admin.createTenantApp('tenant-id', {
+  slug: 'booking-portal',
+  name: 'Booking portal',
+  allowedOrigins: ['https://book.example.com'],
+  allowedRedirectUris: ['https://book.example.com/integrations/connected'],
+  integrationPolicy: {
+    connectors: {
+      google_calendar: { purposes: ['calendar_availability'] },
+      zoom: { purposes: ['meeting_links'] },
+    },
+  },
+});
+const authUrl = await piezas.integrations.getAuthorizationUrl('google_calendar', {
+  appId: 'booking-portal',
+  purpose: 'calendar_availability',
+  userId: 'app-user-1',
+  returnUrl: 'https://book.example.com/integrations/connected',
+});
+```
+
+See the [full SDK documentation](https://www.npmjs.com/package/@piezas/sdk) for more.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "piezas",
+  "version": "0.2.0",
+  "description": "Set up Piezas in your project — installs the SDK and configures AI coding agents",
+  "type": "module",
+  "bin": {
+    "piezas": "src/index.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "piezas",
+    "claude-code",
+    "ai-assisted-coding",
+    "ai-generated-apps",
+    "backend",
+    "api",
+    "sdk"
+  ],
+  "author": "Softmax Data Inc.",
+  "license": "MIT"
+}