kalup 0.1.0

package/docs/targets.md

@@ -0,0 +1,58 @@
+# Targets
+
+A target is a named HubSpot portal under `targets` in `kalup.config.ts`. Call it a target, never an environment.
+
+This page is the reference. For the walk-through with examples, see [Targets and credentials](https://kalup.dev/docs/concepts/targets-and-credentials) on the website.
+
+```ts
+targets: {
+  sandbox: { portalId: 1111111, credentials: { read: { env: 'HUBSPOT_SANDBOX_KEY' } } },
+  production: {
+    portalId: 2222222,
+    protected: true,
+    credentials: { read: { env: 'HUBSPOT_PROD_READ_KEY' } },
+    overrides: { 'property:harvest/picked_on': { name: 'pickedon' } },
+  },
+},
+```
+
+A target may not be named `config` (`E_TARGET_NAME`). A name carries no meaning: protection and drift come from the fields below.
+
+## Choosing a target
+
+`pull`, `plan` and `snapshot` run against one target, picked after the config validates and before any request:
+
+1. `--target <name>`. An undeclared name is `E_UNKNOWN_TARGET`, exit 3, with no fallback.
+2. Else `defaultTarget`, a top-level string in `kalup.config.ts`. One that names no declared target is `E_DEFAULT_TARGET`, exit 3.
+3. Else the only target.
+4. Several targets and none selected: at a terminal (stdin and stderr are terminals, no `--json`, no `CI`), Kalup lists the names and portal IDs and asks; cancelling is `E_CANCELLED`, exit 1. Otherwise `E_TARGET_REQUIRED`, exit 1; an agent should ask the user which one.
+5. No targets: `E_NO_TARGETS`, exit 3.
+
+The first of several targets is never chosen, and no choice is remembered. Text output names the target and how it was picked: `Target sandbox, portal 1111111 (defaultTarget)`.
+
+## Portal pin and guard
+
+`portalId` is required, a positive integer (`E_PORTAL_ID`): the Hub ID from the HubSpot account menu. Two targets may not pin one portal (`E_DUPLICATE_PORTAL`). Every command that reads a target first checks the account-info of its key against the pin. A mismatch is `E_TARGET_PORTAL_MISMATCH`, exit 4, and nothing more is sent with that key.
+
+## Keys
+
+`credentials.read.env` names the variable that holds the read key. Without `credentials` it is `HUBSPOT_SERVICE_KEY`, which `init` always reads. The key comes from the environment, else from the project's `.env`. A missing key is `E_MISSING_KEY`. No output carries a key.
+
+The key goes out as `Authorization: Bearer`. `init` prints the read scopes the pull scope needs; `status` checks each. Both recommend one `crm.objects.<object>.read` scope too: Limits Tracking answered 403 to `crm.schemas.*` scopes alone and 200 with `crm.objects.companies.read` added (developer test account, 2026-09-29); without it `plan` cannot check the property limit (`W_LIMIT_UNREADABLE`). `credentials.write` names the key apply, `state rebuild --write` and `target rebind` use (apply.md); without it they use the read key. That key needs the read scopes and `crm.schemas.<object>.write` per object (`crm.schemas.custom.write` for custom objects), which `init` and `status` list. Neither checks them: read commands never resolve the write key, and no request can check a write scope.
+
+## Overrides
+
+`overrides` is keyed by address: `property:<object>/<name>`, `group:<object>/<name>` or `object:<name>`. A key that is not an address in config is `E_UNKNOWN_OVERRIDE`. Any field other than these four is `E_NOT_DATA`:
+
+- `name: '<portal name>'`: the resource's internal name in this portal. Every read uses it; `plan` blocks it when the portal lacks it. `E_OVERRIDE_AMBIGUOUS` when the portal holds both names; `E_OVERRIDE_NAME` when two addresses would read one portal resource.
+- `skip: true`: left out on this target by every read, a group with its config properties.
+- `definition: {...}`: the fields that differ on this target (config.md).
+- `lookup`: no lookup resource is managed yet; `plan` blocks the resource, `compare` reports it unknown.
+
+## Policy
+
+`protected: true` marks a portal that accepts only saved plans, not covered by `--yes`. `init` writes it for a `STANDARD` account; with config silent, only test portals, sandboxes and app developer accounts are unprotected. `drift` (`'hold'` or `'overwrite'`, default hold) acts only where state holds a base; `adopt` (same values, default hold) decides a unit with no base, as on a first adoption (plan.md). `allowDestroy` (default false) lets a destroy tombstone or takeover delete in this portal. `yesLimit` (0 to 1000, default 25) caps what `--yes` covers; `0` turns it off. `mode` and `objects: { <object>: { mode } }` set takeover per target (config.md). All of them enter the plan's approval digest, and none is inherited from the project or an object but `mode`.
+
+## Rebind
+
+`kalup target rebind <target> --portal <id>` points a target at a recreated test portal or sandbox that no other target pins (`E_DUPLICATE_PORTAL`) and the target's write key belongs to; state.md has the steps. Plans saved for the old portal are refused (`E_PLAN_DESTINATION`).

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "kalup",
+  "version": "0.1.0",
+  "description": "Configuration as code for HubSpot: pull, compare, plan and apply properties and property groups",
+  "keywords": [
+    "hubspot",
+    "crm",
+    "configuration-as-code",
+    "infrastructure-as-code",
+    "iac",
+    "cli",
+    "typescript",
+    "schema",
+    "devops"
+  ],
+  "homepage": "https://kalup.dev",
+  "bugs": {
+    "url": "https://github.com/scopiousdigital/kalup/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scopiousdigital/kalup.git",
+    "directory": "packages/cli"
+  },
+  "license": "Apache-2.0",
+  "author": "Scopious (https://scopious.dev)",
+  "type": "module",
+  "exports": {
+    "./schemas/*.json": "./dist/schemas/*.json"
+  },
+  "bin": {
+    "kalup": "./bin/kalup.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "!dist/build-stamp.json",
+    "docs",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "oclif": {
+    "bin": "kalup",
+    "commands": {
+      "identifier": "COMMANDS",
+      "strategy": "explicit",
+      "target": "./dist/commands.mjs"
+    },
+    "description": "Kalup: configuration as code for HubSpot.",
+    "dirname": "kalup",
+    "topicSeparator": " ",
+    "topics": {
+      "blueprint": {
+        "description": "Upgrade a blueprint added with kalup add."
+      },
+      "state": {
+        "description": "Inspect and rebuild the state file of a target's portal."
+      },
+      "target": {
+        "description": "Change a target's portal."
+      }
+    }
+  },
+  "dependencies": {
+    "@oclif/core": "^5.0.0",
+    "@kalup/core": "0.1.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.23.0",
+    "vitest": "^5.0.1",
+    "@kalup/tsconfig": "0.0.0",
+    "@kalup/engine": "0.0.0"
+  },
+  "engines": {
+    "node": ">=22.13.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:live": "vitest run --config vitest.live.config.ts",
+    "typecheck": "tsc --noEmit"
+  }
+}