kalup 0.1.1 → 0.3.0

package/docs/errors/E_BLUEPRINT_ADDED.md

@@ -4,7 +4,7 @@
 
 ## When
 
-`kalup/blueprints.lock.json` lists each blueprint once, by name. Adding it again would lose its merge base and the conflicts the lock holds, so `add` refuses and points at `kalup blueprint upgrade`, which merges the new version with what the client changed.
+`hubspot/blueprints.lock.json` lists each blueprint once, by name. Adding it again would lose its merge base and the conflicts the lock holds, so `add` refuses and points at `kalup blueprint upgrade`, which merges the new version with what the client changed.
 
 ## Fix
 
@@ -13,5 +13,5 @@ Run the command in the fix, `kalup blueprint upgrade <name> <source>`, to move t
 ## Example
 
 ```
-E_BLUEPRINT_ADDED: acme/renewals is already in kalup/blueprints.lock.json, at version 1.0.0. Nothing was written. (fix: to move to this version, run kalup blueprint upgrade acme/renewals blueprints/renewals-2.0.0.json) (docs: errors/E_BLUEPRINT_ADDED.md)
+E_BLUEPRINT_ADDED: acme/renewals is already in hubspot/blueprints.lock.json, at version 1.0.0. Nothing was written. (fix: to move to this version, run kalup blueprint upgrade acme/renewals blueprints/renewals-2.0.0.json) (docs: errors/E_BLUEPRINT_ADDED.md)
 ```

package/docs/errors/E_BLUEPRINT_INTEGRITY.md

@@ -4,7 +4,7 @@ A blueprint version now has other bytes than the ones Kalup recorded. Exit 1. No
 
 ## When
 
-`sources` in `kalup/blueprints.lock.json` remembers the hash of every source and version ever added or upgraded to. When the same source serves the same version with a different hash, someone changed a published version in place, by mistake or on purpose. Kalup refuses to use it, and names both hashes. `kalup blueprint upgrade` refuses the same version with another hash than the lock holds, from any source.
+`sources` in `hubspot/blueprints.lock.json` remembers the hash of every source and version ever added or upgraded to. When the same source serves the same version with a different hash, someone changed a published version in place, by mistake or on purpose. Kalup refuses to use it, and names both hashes. `kalup blueprint upgrade` refuses the same version with another hash than the lock holds, from any source.
 
 ## Fix
 

package/docs/errors/E_BLUEPRINT_LOCK.md

@@ -1,6 +1,6 @@
 # E_BLUEPRINT_LOCK
 
-`kalup/blueprints.lock.json` is not a valid lock. Exit 3.
+`hubspot/blueprints.lock.json` is not a valid lock. Exit 3.
 
 ## When
 
@@ -8,10 +8,10 @@ The loader reads the lock to add provenance to the resources each blueprint prov
 
 ## Fix
 
-For another lock version, use the version of Kalup that wrote it, or a newer one. Otherwise restore the file from git, for example `git checkout -- kalup/blueprints.lock.json`. After a merge conflict, take one side whole and run `kalup blueprint upgrade` again rather than editing the JSON.
+For another lock version, use the version of Kalup that wrote it, or a newer one. Otherwise restore the file from git, for example `git checkout -- hubspot/blueprints.lock.json`. After a merge conflict, take one side whole and run `kalup blueprint upgrade` again rather than editing the JSON.
 
 ## Example
 
 ```
-kalup/blueprints.lock.json: E_BLUEPRINT_LOCK: sources does not record blueprints/renewals-1.0.0.json@1.0.0 with the hash of acme/renewals (fix: restore kalup/blueprints.lock.json from git: kalup add and kalup blueprint upgrade write it, never a person) (docs: errors/E_BLUEPRINT_LOCK.md)
+hubspot/blueprints.lock.json: E_BLUEPRINT_LOCK: sources does not record blueprints/renewals-1.0.0.json@1.0.0 with the hash of acme/renewals (fix: restore hubspot/blueprints.lock.json from git: kalup add and kalup blueprint upgrade write it, never a person) (docs: errors/E_BLUEPRINT_LOCK.md)
 ```

package/docs/errors/E_BLUEPRINT_ORIGINAL.md

@@ -4,14 +4,14 @@ The stored original of a blueprint is missing, was changed, or is another bluepr
 
 ## When
 
-`kalup blueprint upgrade` merges three ways, with the version the project last added or upgraded to as the base. Kalup keeps that version's bytes under `kalup/.blueprints/` and checks them against the hash in `kalup/blueprints.lock.json`. A deleted file, an edit, a reformat by another tool, a bad merge or git converting line endings (`core.autocrlf`) breaks the base, and a merge against it would misreport what the client changed.
+`kalup blueprint upgrade` merges three ways, with the version the project last added or upgraded to as the base. Kalup keeps that version's bytes under `hubspot/.blueprints/` and checks them against the hash in `hubspot/blueprints.lock.json`. A deleted file, an edit, a reformat by another tool, a bad merge or git converting line endings (`core.autocrlf`) breaks the base, and a merge against it would misreport what the client changed.
 
 ## Fix
 
-Restore the file from git, for example `git checkout -- kalup/.blueprints/acme--renewals@1.0.0.json`, then run the upgrade again. Another blueprint version needs the Kalup that wrote it, or newer. Keep `kalup/.blueprints/` out of formatters and commit it with the lock. `kalup add` writes `kalup/.blueprints/** -text` to `.gitattributes` so git keeps the bytes; if that line is missing, add it back, commit, and check the file out again.
+Restore the file from git, for example `git checkout -- hubspot/.blueprints/acme--renewals@1.0.0.json`, then run the upgrade again. Another blueprint version needs the Kalup that wrote it, or newer. Keep `hubspot/.blueprints/` out of formatters and commit it with the lock. `kalup add` writes `hubspot/.blueprints/** -text` to `.gitattributes` so git keeps the bytes; if that line is missing, add it back, commit, and check the file out again.
 
 ## Example
 
 ```
-E_BLUEPRINT_ORIGINAL: the stored original of acme/renewals 1.0.0, kalup/.blueprints/acme--renewals@1.0.0.json, does not match the hash in kalup/blueprints.lock.json; upgrade merges against it. Nothing was written. (fix: restore it from git, for example git checkout -- kalup/.blueprints/acme--renewals@1.0.0.json, then run kalup blueprint upgrade again) (docs: errors/E_BLUEPRINT_ORIGINAL.md)
+E_BLUEPRINT_ORIGINAL: the stored original of acme/renewals 1.0.0, hubspot/.blueprints/acme--renewals@1.0.0.json, does not match the hash in hubspot/blueprints.lock.json; upgrade merges against it. Nothing was written. (fix: restore it from git, for example git checkout -- hubspot/.blueprints/acme--renewals@1.0.0.json, then run kalup blueprint upgrade again) (docs: errors/E_BLUEPRINT_ORIGINAL.md)
 ```

package/docs/errors/E_BLUEPRINT_SCHEMA.md

@@ -4,7 +4,7 @@ A blueprint is not a valid `blueprint/1` document. Exit 1. Nothing was written.
 
 ## When
 
-`kalup add` and `kalup blueprint upgrade` parse the source as JSON, never as code. Another `blueprintVersion` is refused first. Then they check `blueprint-1.schema.json` and the rules the schema cannot state: addresses of the form `group:<object>/<name>` or `property:<object>/<name>` that match their type, plain names that never start with `hs_` (a group `$ref` names a plain group too), unique option values, aliases that name an option, and a codec that fits the HubSpot type and field type. Text that is not JSON or UTF-8 is refused, and so are names a prefix makes invalid. Each issue names its path; quoted text is sanitized.
+`kalup add` and `kalup blueprint upgrade` parse the source as JSON, never as code. Another `blueprintVersion` is refused first. Then they check `blueprint-1.schema.json` and the rules the schema cannot state: addresses of the form `group:<object>/<name>` or `property:<object>/<name>` that match their type, plain names that never start with a prefix HubSpot reserves, `hs_` or `a<digits>_` (a group `$ref` names a plain group too), unique option values, aliases that name an option, and a codec that fits the HubSpot type and field type. Text that is not JSON or UTF-8 is refused, and so are names a prefix makes invalid. Each issue names its path; quoted text is sanitized.
 
 ## Fix
 
@@ -13,5 +13,5 @@ A blueprint is third-party data: ask its author for a version that passes, `blue
 ## Example
 
 ```
-E_BLUEPRINT_SCHEMA: property name 'hs_renewal_flag' starts with hs_, the prefix HubSpot uses for its own names (fix: a blueprint is third-party data: ask its author for a version that passes, or fix your own copy of the file) (docs: errors/E_BLUEPRINT_SCHEMA.md)
+E_BLUEPRINT_SCHEMA: property name 'hs_renewal_flag' starts with hs_, a prefix HubSpot reserves (fix: a blueprint is third-party data: ask its author for a version that passes, or fix your own copy of the file) (docs: errors/E_BLUEPRINT_SCHEMA.md)
 ```

package/docs/errors/E_BLUEPRINT_SOURCE.md

@@ -8,7 +8,7 @@ A source is a path to a JSON file, relative to the current directory, or an `htt
 
 ## Fix
 
-Pass a path to the blueprint file, or an https URL that serves it. For a private URL, download the file and pass its path. Check the name against `kalup/blueprints.lock.json` for an upgrade.
+Pass a path to the blueprint file, or an https URL that serves it. For a private URL, download the file and pass its path. Check the name against `hubspot/blueprints.lock.json` for an upgrade.
 
 ## Example
 

package/docs/errors/E_BLUEPRINT_UNKNOWN.md

@@ -4,7 +4,7 @@
 
 ## When
 
-Upgrade merges against the stored original of a blueprint the project added. The name must be one `kalup/blueprints.lock.json` lists; the message names them.
+Upgrade merges against the stored original of a blueprint the project added. The name must be one `hubspot/blueprints.lock.json` lists; the message names them.
 
 ## Fix
 
@@ -13,5 +13,5 @@ Use a name the lock lists, or add the blueprint first with `kalup add <source>`.
 ## Example
 
 ```
-E_BLUEPRINT_UNKNOWN: acme/billing is not in kalup/blueprints.lock.json, which lists acme/renewals (fix: add it first with kalup add <source>, or name a blueprint the lock lists) (docs: errors/E_BLUEPRINT_UNKNOWN.md)
+E_BLUEPRINT_UNKNOWN: acme/billing is not in hubspot/blueprints.lock.json, which lists acme/renewals (fix: add it first with kalup add <source>, or name a blueprint the lock lists) (docs: errors/E_BLUEPRINT_UNKNOWN.md)
 ```

package/docs/errors/E_DEFINITION_FIELD.md

@@ -0,0 +1,29 @@
+# E_DEFINITION_FIELD
+
+A property definition states a field HubSpot would refuse or misread for this property. Exit 3.
+
+## When
+
+`validate` and every command that validates first check the fields that depend on the builder or on each other, as HubSpot does:
+
+- `numberDisplayHint`, `showCurrencySymbol` and `currencyPropertyName` belong to `p.number`, and `textDisplayHint` to `p.string`, `p.stringArray`, `p.json` and `p.phoneNumber`. HubSpot stores them on any property but shows them only on those.
+- `calculationFormula` needs `fieldType: 'calculation_equation'`. Sent with another field type, HubSpot turns the property into a calculation.
+- `currencyPropertyName` needs `showCurrencySymbol: true`. HubSpot refuses it otherwise (`ONLY_CURRENCY_PROPERTIES_CAN_SPECIFY_CURRENCY`), and an empty `''` is refused by Kalup: HubSpot stores it as a value and then never turns the symbol off again (live runs, 2026-10-01).
+- `displayOrder` is an integer from -1 up.
+- `p.owner` takes no `options`: HubSpot fills them with the account's users and refuses a create that sends any.
+
+A target's definition override that breaks one of these rules is `E_OVERRIDE_DEFINITION`.
+
+## Fix
+
+Change or remove the field the message names, or change the builder.
+
+## Example
+
+```ts
+share: p.string('pick_share', { label: 'Pick share', group: 'orchard', fieldType: 'text', numberDisplayHint: 'percentage' }),
+```
+
+```
+hubspot/objects/companies.ts:14: E_DEFINITION_FIELD: numberDisplayHint is for p.number, not p.string (fix: remove numberDisplayHint) (docs: errors/E_DEFINITION_FIELD.md)
+```

package/docs/errors/E_DIR_AMBIGUOUS.md

@@ -0,0 +1,17 @@
+# E_DIR_AMBIGUOUS
+
+Both `hubspot/` and the old default folder `kalup/` hold .ts files, and `kalup.config.ts` does not say which one holds the object files. Exit 3. Nothing was read or written.
+
+## When
+
+Without `dir` in `kalup.config.ts`, Kalup reads `hubspot/`, or an older project's `kalup/` while `hubspot/` holds no .ts file (`W_LEGACY_DIR`). When both hold .ts files, such as a half-done move or a HubSpot developer project in `hubspot/`, Kalup does not guess: reading the wrong folder would make everything in the other look removed from config.
+
+## Fix
+
+Add `dir: 'kalup'` to `kalup.config.ts` to keep the old folder, or `dir: 'hubspot'` when the object files are there. Then move or remove the other folder's copy of the object files.
+
+## Example
+
+```
+kalup.config.ts: E_DIR_AMBIGUOUS: both hubspot/ and kalup/ hold .ts files, and kalup.config.ts does not say which one holds the object files (fix: add dir: 'kalup' to kalup.config.ts to keep the old folder, or dir: 'hubspot' when the object files are there) (docs: errors/E_DIR_AMBIGUOUS.md)
+```

package/docs/errors/E_DIR_IN_USE.md

@@ -0,0 +1,17 @@
+# E_DIR_IN_USE
+
+`init` refused to run because the folder of object files holds a .ts file that is not Kalup's, or is a file. Exit 1. Nothing was written.
+
+## When
+
+The folder `--dir` names (`hubspot/` without it) belongs to Kalup alone: every command reads each .ts file in it as an object file, `pull` rewrites its `index.ts`, and `init` takes the folder out of the formatter's checks. A folder such as `lib/config` that already holds the app's own modules cannot be it. Object files, `removed.ts` and the `index.ts` barrel from an earlier `init` or `pull` are Kalup's, so `init` runs again after `kalup.config.ts` is removed.
+
+## Fix
+
+Pass `--dir` with a folder of its own, such as `lib/config/hubspot`, or move the file out of the folder.
+
+## Example
+
+```
+lib/config/index.ts: E_DIR_IN_USE: lib/config/index.ts is not a kalup file, and lib/config/ must hold kalup's files only. Nothing was written. (fix: pass --dir with a folder of its own, such as lib/config/hubspot) (docs: errors/E_DIR_IN_USE.md)
+```

package/docs/errors/E_DUPLICATE_ADDRESS.md

@@ -13,5 +13,5 @@ Keep one definition and remove the other, or give one of them another internal n
 ## Example
 
 ```
-kalup/objects/companies.ts:15: E_DUPLICATE_ADDRESS: group:companies/orchard is defined twice: kalup/objects/companies.ts:5 and kalup/objects/companies.ts:15 (fix: remove or rename one of the two definitions) (docs: errors/E_DUPLICATE_ADDRESS.md)
+hubspot/objects/companies.ts:15: E_DUPLICATE_ADDRESS: group:companies/orchard is defined twice: hubspot/objects/companies.ts:5 and hubspot/objects/companies.ts:15 (fix: remove or rename one of the two definitions) (docs: errors/E_DUPLICATE_ADDRESS.md)
 ```

package/docs/errors/E_DUPLICATE_ALIAS.md

@@ -20,5 +20,5 @@ options: [
 ```
 
 ```
-kalup/objects/companies.ts:14: E_DUPLICATE_ALIAS: options 'CLAY' and 'clay' share the alias 'clay' (fix: give one of them another as; an option without as uses its value as the alias) (docs: errors/E_DUPLICATE_ALIAS.md)
+hubspot/objects/companies.ts:14: E_DUPLICATE_ALIAS: options 'CLAY' and 'clay' share the alias 'clay' (fix: give one of them another as; an option without as uses its value as the alias) (docs: errors/E_DUPLICATE_ALIAS.md)
 ```

package/docs/errors/E_DUPLICATE_KEY.md

@@ -20,5 +20,5 @@ properties: {
 ```
 
 ```
-kalup/objects/companies.ts:9: E_DUPLICATE_KEY: internal name 'plot_count' is used by two keys of Company: 'plotCount' and 'plotTotal' (fix: remove or rename one of the two entries) (docs: errors/E_DUPLICATE_KEY.md)
+hubspot/objects/companies.ts:9: E_DUPLICATE_KEY: internal name 'plot_count' is used by two keys of Company: 'plotCount' and 'plotTotal' (fix: remove or rename one of the two entries) (docs: errors/E_DUPLICATE_KEY.md)
 ```

package/docs/errors/E_DUPLICATE_OPTION.md

@@ -21,5 +21,5 @@ options: [
 ```
 
 ```
-kalup/objects/companies.ts:14: E_DUPLICATE_OPTION: option value 'clay' is listed twice (fix: remove one of the two options) (docs: errors/E_DUPLICATE_OPTION.md)
+hubspot/objects/companies.ts:14: E_DUPLICATE_OPTION: option value 'clay' is listed twice (fix: remove one of the two options) (docs: errors/E_DUPLICATE_OPTION.md)
 ```

package/docs/errors/E_HS_PREFIX.md

@@ -1,10 +1,10 @@
 # E_HS_PREFIX
 
-A managed property's internal name starts with `hs_`. Exit 3.
+A managed property's internal name starts with `hs_` or `a<digits>_`. Exit 3.
 
 ## When
 
-HubSpot uses `hs_` for its own properties. Kalup never claims that prefix for a property it would own. Whether HubSpot refuses such a create is not confirmed. A reference (no definition) may carry the prefix.
+HubSpot reserves `hs_` for its own properties and `a<appId>_` for an integration's, and refuses a create with either (400, live runs 2026-10-01). Kalup never claims those prefixes for a property it would own; `pull` writes such a property as a reference. A reference (no definition) may carry the prefix.
 
 ## Fix
 
@@ -17,5 +17,5 @@ plotCount: p.number('hs_plot_count', { label: 'Plot count', group: 'orchard', fi
 ```
 
 ```
-kalup/objects/companies.ts:9: E_HS_PREFIX: 'hs_plot_count' starts with hs_, the prefix HubSpot uses for its own properties (fix: rename the property, or drop label, group and fieldType to reference it) (docs: errors/E_HS_PREFIX.md)
+hubspot/objects/companies.ts:9: E_HS_PREFIX: 'hs_plot_count' starts with hs_, a prefix HubSpot reserves (hs_ for its own properties, a<digits>_ for an integration's) (fix: rename the property, or drop label, group and fieldType to reference it) (docs: errors/E_HS_PREFIX.md)
 ```

package/docs/errors/E_HTTP.md

@@ -4,7 +4,7 @@ HubSpot returned an error Kalup has no other code for. Exit 1.
 
 ## When
 
-A 400, a 404, a 5xx that three retries did not clear, or a success whose body is not JSON (often a proxy's HTML page). The issue holds the status, the method, the path and HubSpot's message when it sent one. In `apply`, a refusal whose reason HubSpot names and Kalup knows says it in plain words: a property in use, a group that still holds properties, or a property name that exists.
+A 400, a 404, a 5xx that three retries did not clear, or a success whose body is not JSON (often a proxy's HTML page). The issue holds the status, the method, the path and HubSpot's message when it sent one. In `apply`, a refusal whose reason HubSpot names and Kalup knows says it in plain words: a property in use (each workflow, list, form or calculation named), a group that still holds active properties, a property name that exists, a currency symbol HubSpot never turns off again, or a sensitive property on a portal with sensitive data turned off.
 
 ## Fix
 

package/docs/errors/E_KEY_COLLISION.md

@@ -18,5 +18,5 @@ export const CompanyExtra = defineObject('companies', { properties: { owner: p.s
 ```
 
 ```
-kalup/objects/companies.ts:39: E_KEY_COLLISION: key 'owner' is used by two properties of companies: property:companies/orch_owner and property:companies/orch_owner_name (fix: rename one of the two keys) (docs: errors/E_KEY_COLLISION.md)
+hubspot/objects/companies.ts:39: E_KEY_COLLISION: key 'owner' is used by two properties of companies: property:companies/orch_owner and property:companies/orch_owner_name (fix: rename one of the two keys) (docs: errors/E_KEY_COLLISION.md)
 ```

package/docs/errors/E_LIFECYCLE.md

@@ -4,7 +4,7 @@ A `lifecycle` block contradicts itself. Exit 3.
 
 ## When
 
-`removedOptions` names a value that is still in `options`, or `ignoreChanges` names something other than `label`, `group`, `fieldType`, `description`, `options`, `hasUniqueValue` or `formField`.
+`removedOptions` names a value that is still in `options`, or `ignoreChanges` names something other than a definition field: `label`, `group`, `fieldType`, `description`, `options`, `hasUniqueValue`, `formField`, `hidden`, `displayOrder`, `numberDisplayHint`, `showCurrencySymbol`, `currencyPropertyName`, `textDisplayHint`, `calculationFormula` or `dataSensitivity`.
 
 ## Fix
 
@@ -18,6 +18,6 @@ lifecycle: { removedOptions: ['clay'], ignoreChanges: ['colour'] },
 ```
 
 ```
-kalup/objects/companies.ts:14: E_LIFECYCLE: removedOptions names 'clay', which is still in options (fix: remove it from options or from removedOptions) (docs: errors/E_LIFECYCLE.md)
-kalup/objects/companies.ts:14: E_LIFECYCLE: ignoreChanges names 'colour', which is not a definition field (fix: use one of label, group, fieldType, description, options, hasUniqueValue, formField) (docs: errors/E_LIFECYCLE.md)
+hubspot/objects/companies.ts:14: E_LIFECYCLE: removedOptions names 'clay', which is still in options (fix: remove it from options or from removedOptions) (docs: errors/E_LIFECYCLE.md)
+hubspot/objects/companies.ts:14: E_LIFECYCLE: ignoreChanges names 'colour', which is not a definition field (fix: use one of label, group, fieldType, description, options, hasUniqueValue, formField) (docs: errors/E_LIFECYCLE.md)
 ```

package/docs/errors/E_LOCKED.md

@@ -4,7 +4,7 @@ Another Kalup command holds the lock of this portal. Exit 1. Kalup does not wait
 
 ## When
 
-Commands that write to a portal or its state take a lock named by the portal ID before they read state, and hold it until state is saved: `apply`, `state rebuild --write`, `target rebind`, and `pull` and `init` whenever they may record bases (not with `--check` or `--discover`). The lock is a file in `~/.kalup/locks` (or `KALUP_LOCK_DIR`) that names the holder's command, plan, host, process ID and start time. It keeps apart the writers of one user on one machine, across clones, worktrees and target names. Kalup never takes a lock over, even when its holder has ended: a command that crashed or was killed leaves its lock behind until a person deletes it.
+Commands that write to a portal or its state take a lock named by the portal ID before they read state, and hold it until state is saved: `apply`, `state rebuild --write`, `target rebind`, and `pull` whenever it may record bases (not with `--check` or `--discover`). The lock is a file in `~/.kalup/locks` (or `KALUP_LOCK_DIR`) that names the holder's command, plan, host, process ID and start time. It keeps apart the writers of one user on one machine, across clones, worktrees and target names. Kalup never takes a lock over, even when its holder has ended: a command that crashed or was killed leaves its lock behind until a person deletes it.
 
 ## Fix
 

package/docs/errors/E_MISSING_EXPORT.md

@@ -1,17 +1,17 @@
 # E_MISSING_EXPORT
 
-A file under `kalup/` has no `defineObject` or `defineCustomObject` export. Exit 3.
+A file under `hubspot/` has no `defineObject` or `defineCustomObject` export. Exit 3.
 
 ## When
 
-Kalup reads every `.ts` file under `kalup/` except `kalup/index.ts` as an object file. A file with only imports, or an empty file, has nothing to read.
+Kalup reads every `.ts` file in the folder of object files (`hubspot/`, or the folder `dir` in `kalup.config.ts` names) except `index.ts` and `removed.ts` as an object file. A file with only imports, or an empty file, has nothing to read.
 
 ## Fix
 
-Add the export, or move the file out of `kalup/`.
+Add the export, or move the file out of `hubspot/`.
 
 ## Example
 
 ```
-kalup/objects/empty.ts:1: E_MISSING_EXPORT: no defineObject or defineCustomObject export in this file (fix: add `export const <Name> = defineObject('<object>', {...})`) (docs: errors/E_MISSING_EXPORT.md)
+hubspot/objects/empty.ts:1: E_MISSING_EXPORT: no defineObject or defineCustomObject export in this file (fix: add `export const <Name> = defineObject('<object>', {...})`) (docs: errors/E_MISSING_EXPORT.md)
 ```

package/docs/errors/E_MISSING_KEY.md

@@ -4,7 +4,7 @@ The variable that should hold the read key is not set. Exit 1.
 
 ## When
 
-The variable is `credentials.read.env` of the target, or `HUBSPOT_SERVICE_KEY` when the target has no `credentials`. In this version `init` has no `--env` flag and always reads `HUBSPOT_SERVICE_KEY`. Kalup looks in the process environment, then in `.env` in the project directory. `status` reports it per target and checks the others.
+The variable is `credentials.read.env` of the target, or `HUBSPOT_SERVICE_KEY` when the target has no `credentials`. `init` writes no `credentials`, so a new project reads `HUBSPOT_SERVICE_KEY`. Kalup looks in the process environment, then in `.env` in the project directory. `status` reports it per target and checks the others.
 
 ## Fix
 

package/docs/errors/E_NOT_DATA.md

@@ -17,5 +17,5 @@ plotCount: p.number('plot_count'), // counted by hand
 ```
 
 ```
-kalup/objects/companies.ts:5: E_NOT_DATA: this comment is not attached to an entry (fix: move this comment above the entry it describes) (docs: errors/E_NOT_DATA.md)
+hubspot/objects/companies.ts:5: E_NOT_DATA: this comment is not attached to an entry (fix: move this comment above the entry it describes) (docs: errors/E_NOT_DATA.md)
 ```

package/docs/errors/E_OVERRIDE_DEFINITION.md

@@ -6,9 +6,9 @@ A target's definition override states something that cannot differ per target. E
 
 `overrides: { '<address>': { definition: {...} } }` replaces fields of the shared definition on one target. `validate` and every command that validates first report, at the override's line:
 
-- a field other than `label`, `description`, `group`, `fieldType`, `formField` and `options` on a property, or `label` on a group. `hasUniqueValue` is fixed when HubSpot creates a property, and `type` comes from the builder. In `lifecycle`, only `options`, `removedOptions` and `ignoreChanges`.
+- a field other than `label`, `description`, `group`, `fieldType`, `formField`, `options`, `hidden`, `displayOrder`, the display fields and `calculationFormula` on a property, or `label` on a group. `hasUniqueValue` and `dataSensitivity` are fixed when HubSpot creates a property, and `type` comes from the builder. In `lifecycle`, only `options`, `removedOptions` and `ignoreChanges`.
 - an override on a reference, a `.managed(false)` property or a custom object schema.
-- a result that breaks a shared rule: a `fieldType` the builder does not take, a `group` the object does not declare, an option value twice, `removedOptions` naming a kept option, `ignoreChanges` naming no definition field.
+- a result that breaks a shared rule: a `fieldType` the builder does not take, a `group` the object does not declare, an option value twice, `removedOptions` naming a kept option, `ignoreChanges` naming no definition field, or a rule of `E_DEFINITION_FIELD`.
 - an option with `as`. Aliases belong to the app and stay in the shared file.
 
 ## Fix

package/docs/errors/E_PENDING_TARGET.md

@@ -0,0 +1,17 @@
+# E_PENDING_TARGET
+
+The command needs the portal of a target that has no `portalId` yet. Exit 3. Nothing was sent.
+
+## When
+
+`kalup init` without `--portal` writes a pending target: a name and no `portalId`, since init never asks HubSpot. `validate`, `ir`, `fmt`, `rm`, `add` and `docs` work with it. A command that reads or writes the portal (`pull`, `plan`, `apply`, `compare`, `snapshot`, `state rebuild`, `target rebind`) refuses it before any request, because the portal guard has nothing to check the key against. `status` lists it as pending.
+
+## Fix
+
+Set `targets.<name>.portalId` in `kalup.config.ts` to the Hub ID from the HubSpot account menu, then run the command again.
+
+## Example
+
+```
+kalup.config.ts: E_PENDING_TARGET: target production has no portalId yet, so pull cannot check the key against its portal. Nothing was sent. (fix: set targets.production.portalId in kalup.config.ts to the Hub ID from the HubSpot account menu) (docs: errors/E_PENDING_TARGET.md)
+```

package/docs/errors/E_PLAN_DELETE.md

@@ -4,7 +4,7 @@ A saved plan deletes something config does not ask to delete. Exit 1. Nothing wa
 
 ## When
 
-A delete needs a `destroy` tombstone that `kalup rm` wrote, or takeover to ask for it (the mode of the object on the target is takeover, the address is in the pull scope, neither `exclude`, a `skip` override nor a tombstone names it, and the step carries the `takeover` label), and an address gone from config. Before approval, `kalup apply` reads `kalup/removed.ts` and the object files as data, never running them, and refuses a delete step whose address has neither, is still in config, or sets `lifecycle.preventDestroy`; the message says why takeover does not archive it. It also refuses a delete of a portal resource that another address in config names through a name override on the target. The tombstone was removed after planning, the resource came back into config or into `exclude`, or the plan file was edited.
+A delete needs a `destroy` tombstone that `kalup rm` wrote, or takeover to ask for it (the mode of the object on the target is takeover, the address is in the pull scope, neither `exclude`, a `skip` override nor a tombstone names it, and the step carries the `takeover` label), and an address gone from config. Before approval, `kalup apply` reads `hubspot/removed.ts` and the object files as data, never running them, and refuses a delete step whose address has neither, is still in config, or sets `lifecycle.preventDestroy`; the message says why takeover does not archive it. It also refuses a delete of a portal resource that another address in config names through a name override on the target. The tombstone was removed after planning, the resource came back into config or into `exclude`, or the plan file was edited.
 
 ## Fix
 

package/docs/errors/E_PORTAL_ID.md

@@ -1,10 +1,10 @@
 # E_PORTAL_ID
 
-A target has no `portalId`, or it is not a positive integer. Exit 3.
+A target's `portalId` is not a positive integer. Exit 3.
 
 ## When
 
-`portalId` pins the target to one portal. Every networked command checks the key against it.
+`portalId` pins the target to one portal. Every networked command checks the key against it. A target with no `portalId` at all is pending (`W_PENDING_TARGET`), not this error.
 
 ## Fix
 

package/docs/errors/E_PREVENT_DESTROY.md

@@ -13,5 +13,5 @@ To delete it after all, remove `preventDestroy` from its lifecycle first, then r
 ## Example
 
 ```
-kalup/objects/companies.ts:14: E_PREVENT_DESTROY: property:companies/soil_ph sets lifecycle.preventDestroy, so rm does not write a destroy tombstone for it. Nothing was written. (fix: remove preventDestroy from its lifecycle first, or run kalup rm property:companies/soil_ph --release to stop managing it and leave it in HubSpot) (docs: errors/E_PREVENT_DESTROY.md)
+hubspot/objects/companies.ts:14: E_PREVENT_DESTROY: property:companies/soil_ph sets lifecycle.preventDestroy, so rm does not write a destroy tombstone for it. Nothing was written. (fix: remove preventDestroy from its lifecycle first, or run kalup rm property:companies/soil_ph --release to stop managing it and leave it in HubSpot) (docs: errors/E_PREVENT_DESTROY.md)
 ```

package/docs/errors/E_PROJECT_WRITE.md

@@ -13,5 +13,5 @@ Check that the project directory is writable and the disk has room, then run the
 ## Example
 
 ```
-E_PROJECT_WRITE: could not write kalup/index.ts, kalup/objects/companies.ts, kalup/removed.ts (ENOSPC). Every file was left as it was. (fix: check that the project directory is writable and the disk has room, then run the command again) (docs: errors/E_PROJECT_WRITE.md)
+E_PROJECT_WRITE: could not write hubspot/index.ts, hubspot/objects/companies.ts, hubspot/removed.ts (ENOSPC). Every file was left as it was. (fix: check that the project directory is writable and the disk has room, then run the command again) (docs: errors/E_PROJECT_WRITE.md)
 ```

package/docs/errors/E_PROTECTED_SAVED_PLAN.md

@@ -1,17 +1,17 @@
 # E_PROTECTED_SAVED_PLAN
 
-`kalup apply` without a plan file does not run on a protected target. Exit 1. Nothing was written.
+`kalup apply` without a plan file on a protected target needs a person at a terminal. Exit 4, `humanRequired: true`. Nothing was written.
 
 ## When
 
-Without a file, `kalup apply` plans the target and applies that plan in one run. That is only for an unprotected target, such as a sandbox. A protected target (`protected: true`, and unless config says otherwise every account but a `DEVELOPER_TEST`, `SANDBOX` or `APP_DEVELOPER` one) accepts only a saved plan that a person reviewed.
+Without a file, `kalup apply` plans the target and applies that plan in one run. On a protected target (`protected: true`, and unless config says otherwise every account but a `DEVELOPER_TEST`, `SANDBOX` or `APP_DEVELOPER` one) a person at a terminal reviews that plan there and confirms it by typing the target name, and the number of destructive steps when there are any. Here nobody can: stdin or stderr is not a terminal, `--json` is set, or `CI` is. Apply stops after the portal guard, before it plans.
 
 ## Fix
 
-Run `kalup plan --target <name> --out plan.json` and review the plan. Then a person runs `kalup apply plan.json` in a terminal and confirms it.
+Stop. Hand the command in the fix to the user, who runs it in a terminal and confirms it there. In CI, save the plan with `kalup plan --target <name> --out` for review, and let the reviewed job apply that file. Agents never approve on the user's behalf.
 
 ## Example
 
 ```
-E_PROTECTED_SAVED_PLAN: target production is protected, so it accepts only a saved plan that a person reviewed. Nothing was written. (fix: run kalup plan --target production --out plan.json, review it, then ask the user to run kalup apply plan.json in a terminal) (docs: errors/E_PROTECTED_SAVED_PLAN.md)
+E_PROTECTED_SAVED_PLAN: target production is protected: applying it without a plan file needs a person at a terminal to confirm the plan, and there is none here (no terminal, --json, or CI set). Nothing was written. (fix: ask the user to run kalup apply --target production in a terminal, where they confirm it; in CI, apply a plan saved with kalup plan --target production --out after review) (docs: errors/E_PROTECTED_SAVED_PLAN.md)
 ```

package/docs/errors/E_PULL_INVALID.md

@@ -6,7 +6,7 @@ The files `pull` merged would not load or validate, so it wrote nothing. Exit 3,
 
 Pull merges the portal into the object files, then loads and validates the whole project as it would write it, before saving anything. The issues after this one are what `validate` would report, with the file and line in the merged text, not the file on disk.
 
-Two examples: a property HubSpot does not define whose name starts with `hs_` (`E_HS_PREFIX`), and a new property whose key is taken twice (`E_DUPLICATE_KEY`).
+An example: a new property whose internal name another key of the same object already uses (`E_DUPLICATE_KEY`).
 
 ## Fix
 
@@ -16,5 +16,5 @@ Change the portal or the file so the two agree, then pull again. To pull everyth
 
 ```
 E_PULL_INVALID: the pulled project would not validate; nothing was written (fix: the issues that follow point at the files as pull would write them: change the portal or the file so they agree, or leave the resource out with --only) (docs: errors/E_PULL_INVALID.md)
-kalup/objects/companies.ts:20: E_HS_PREFIX: 'hs_orchard_score' starts with hs_, the prefix HubSpot uses for its own properties (fix: rename the property, or drop label, group and fieldType to reference it) (docs: errors/E_HS_PREFIX.md)
+hubspot/objects/companies.ts:20: E_DUPLICATE_KEY: internal name 'plot_count' is used by two keys of Company: 'plotCount' and 'plotTotal' (fix: remove or rename one of the two entries) (docs: errors/E_DUPLICATE_KEY.md)
 ```

package/docs/errors/E_REFERENCE_DEFINITION.md

@@ -17,5 +17,5 @@ plotTotal: p.number('plot_total', { label: 'Plot total' }),
 ```
 
 ```
-kalup/objects/companies.ts:23: E_REFERENCE_DEFINITION: a definition needs label, group and fieldType (fix: add the missing fields, or drop the definition) (docs: errors/E_REFERENCE_DEFINITION.md)
+hubspot/objects/companies.ts:23: E_REFERENCE_DEFINITION: a definition needs label, group and fieldType (fix: add the missing fields, or drop the definition) (docs: errors/E_REFERENCE_DEFINITION.md)
 ```

package/docs/errors/E_RM_DEPENDENTS.md

@@ -13,5 +13,5 @@ Move those properties to another group, or remove them first (with `kalup rm` fo
 ## Example
 
 ```
-kalup/objects/companies.ts:6: E_RM_DEPENDENTS: group:companies/orchard cannot leave config while properties in config use it: property:companies/soil_ph. Nothing was written. (fix: remove or change those first, then run rm again) (docs: errors/E_RM_DEPENDENTS.md)
+hubspot/objects/companies.ts:6: E_RM_DEPENDENTS: group:companies/orchard cannot leave config while properties in config use it: property:companies/soil_ph. Nothing was written. (fix: remove or change those first, then run rm again) (docs: errors/E_RM_DEPENDENTS.md)
 ```

package/docs/errors/E_SETTING_VALUE.md

@@ -6,11 +6,13 @@ A setting in kalup.config.ts has a value it does not allow. Exit 3.
 
 `mode` takes `'addon'` or `'takeover'`; `drift` and `adopt` take `'hold'` or `'overwrite'`; `yesLimit` takes an integer from 0 to 1000. The fix names the nearest allowed value.
 
+`dir` takes a folder inside the project, relative to `kalup.config.ts`: not an absolute path, not one that leaves the project through `..`, and not the project directory itself.
+
 `validate` also reports a name that `include` and `exclude` of one object both list, and a `targets.<target>.objects` key that `objects` does not declare.
 
 ## Fix
 
-Write the value the fix suggests, or another allowed one. Remove a name from one of `include` and `exclude`.
+Write the value the fix suggests, or another allowed one. Remove a name from one of `include` and `exclude`. Write `dir` as a relative path such as `'lib/config/hubspot'`, or remove it to use `hubspot/`.
 
 ## Example
 

package/docs/errors/E_STANDARD_OBJECT.md

@@ -17,5 +17,5 @@ export const Company = defineCustomObject('companies', { labels: { singular: 'Co
 ```
 
 ```
-kalup/objects/companies.ts:6: E_STANDARD_OBJECT: 'companies' is a standard object in HubSpot, so defineCustomObject cannot define it (fix: use defineObject('companies', ...) without labels and the display properties, or name the custom object differently) (docs: errors/E_STANDARD_OBJECT.md)
+hubspot/objects/companies.ts:6: E_STANDARD_OBJECT: 'companies' is a standard object in HubSpot, so defineCustomObject cannot define it (fix: use defineObject('companies', ...) without labels and the display properties, or name the custom object differently) (docs: errors/E_STANDARD_OBJECT.md)
 ```

package/docs/errors/E_STRICT_WITHOUT_OPTIONS.md

@@ -17,5 +17,5 @@ stage: p.enum('lifecyclestage').strict(),
 ```
 
 ```
-kalup/objects/companies.ts:9: E_STRICT_WITHOUT_OPTIONS: .strict() on 'lifecyclestage', which lists no options, so its codec would throw on every value (fix: list the options, or drop .strict()) (docs: errors/E_STRICT_WITHOUT_OPTIONS.md)
+hubspot/objects/companies.ts:9: E_STRICT_WITHOUT_OPTIONS: .strict() on 'lifecyclestage', which lists no options, so its codec would throw on every value (fix: list the options, or drop .strict()) (docs: errors/E_STRICT_WITHOUT_OPTIONS.md)
 ```

package/docs/errors/E_TARGET_PORTAL_MISMATCH.md

@@ -4,7 +4,7 @@ The key belongs to another portal than the one pinned. Exit 4, `humanRequired: t
 
 ## When
 
-Every command that reads a target first checks account-info with its key; `init` and `target rebind` check the portal `--portal` gives. The key's portal differs, so nothing more is sent with that key and nothing is written. `status` still checks the other targets with their own keys.
+Every command that reads a target first checks account-info with its key; `target rebind` checks the portal `--portal` gives. The key's portal differs, so nothing more is sent with that key and nothing is written. `status` still checks the other targets with their own keys.
 
 ## Fix
 

package/docs/errors/E_TOMBSTONE_ADDRESS.md

@@ -1,10 +1,10 @@
 # E_TOMBSTONE_ADDRESS
 
-A key in `kalup/removed.ts`, or the address given to `kalup rm`, is not the address of a property or group. Exit 3.
+A key in `hubspot/removed.ts`, or the address given to `kalup rm`, is not the address of a property or group. Exit 3.
 
 ## When
 
-Each key in `kalup/removed.ts` is an address, such as `property:companies/legacy_score`: the type, a colon, the object, a slash and the name. A key with no object, such as `property:legacy_score`, names nothing and is refused. This version removes properties and property groups only, so a key of another type, such as `object:parcels`, is refused as well.
+Each key in `hubspot/removed.ts` is an address, such as `property:companies/legacy_score`: the type, a colon, the object, a slash and the name. A key with no object, such as `property:legacy_score`, names nothing and is refused. This version removes properties and property groups only, so a key of another type, such as `object:parcels`, is refused as well.
 
 ## Fix
 
@@ -19,5 +19,5 @@ export default defineRemoved({
 ```
 
 ```
-kalup/removed.ts:4: E_TOMBSTONE_ADDRESS: 'legacyScore' is not an address (fix: write the address of a property or group, such as 'property:companies/legacy_score') (docs: errors/E_TOMBSTONE_ADDRESS.md)
+hubspot/removed.ts:4: E_TOMBSTONE_ADDRESS: 'legacyScore' is not an address (fix: write the address of a property or group, such as 'property:companies/legacy_score') (docs: errors/E_TOMBSTONE_ADDRESS.md)
 ```

package/docs/errors/E_TOMBSTONE_CONFLICT.md

@@ -1,10 +1,10 @@
 # E_TOMBSTONE_CONFLICT
 
-An address is in `kalup/removed.ts` and still defined in config. Exit 3.
+An address is in `hubspot/removed.ts` and still defined in config. Exit 3.
 
 ## When
 
-A tombstone takes a resource out of config: `destroy` deletes it in the portal, `release` stops managing it and leaves it there. Config may not define the same address at the same time, not even as a reference without `label`, `group` and `fieldType`. This usually means the entry was added to `kalup/removed.ts` by hand and the property or group was left in its object file.
+A tombstone takes a resource out of config: `destroy` deletes it in the portal, `release` stops managing it and leaves it there. Config may not define the same address at the same time, not even as a reference without `label`, `group` and `fieldType`. This usually means the entry was added to `hubspot/removed.ts` by hand and the property or group was left in its object file.
 
 ## Fix
 
@@ -13,5 +13,5 @@ Remove the property or group from its object file. `kalup rm <address>` does bot
 ## Example
 
 ```
-kalup/removed.ts:4: E_TOMBSTONE_CONFLICT: property:companies/legacy_score is in kalup/removed.ts and in config (fix: remove it from config, or run kalup rm, which does both) (docs: errors/E_TOMBSTONE_CONFLICT.md)
+hubspot/removed.ts:4: E_TOMBSTONE_CONFLICT: property:companies/legacy_score is in hubspot/removed.ts and in config (fix: remove it from config, or run kalup rm, which does both) (docs: errors/E_TOMBSTONE_CONFLICT.md)
 ```

package/docs/errors/E_TYPE_FIELDTYPE.md

@@ -4,7 +4,7 @@ A `fieldType` the builder does not allow. Exit 3.
 
 ## When
 
-Each builder allows some `fieldType` values. `p.enum` takes `select`, `radio` or `booleancheckbox`, and `p.multiEnum` only `checkbox`. [config.md](../config.md#builders) has the full list.
+Each builder allows some `fieldType` values. `p.enum` takes `select`, `radio`, `booleancheckbox` or `calculation_equation`, and `p.multiEnum` only `checkbox`. [config.md](../config.md#builders) has the full list.
 
 ## Fix
 
@@ -17,5 +17,5 @@ soil: p.enum('soil_type', { label: 'Soil type', group: 'orchard', fieldType: 'ch
 ```
 
 ```
-kalup/objects/companies.ts:14: E_TYPE_FIELDTYPE: fieldType 'checkbox' is not allowed for p.enum (type enumeration) (fix: use one of 'select', 'radio', 'booleancheckbox') (docs: errors/E_TYPE_FIELDTYPE.md)
+hubspot/objects/companies.ts:14: E_TYPE_FIELDTYPE: fieldType 'checkbox' is not allowed for p.enum (type enumeration) (fix: use one of 'select', 'radio', 'booleancheckbox', 'calculation_equation') (docs: errors/E_TYPE_FIELDTYPE.md)
 ```

package/docs/errors/E_UNKNOWN_BUILDER.md

@@ -4,7 +4,7 @@
 
 ## When
 
-The builders are `p.string`, `p.number`, `p.boolean`, `p.date`, `p.datetime`, `p.enum`, `p.multiEnum`, `p.stringArray` and `p.json`. HubSpot field types such as `text` are not builders.
+The builders are `p.string`, `p.number`, `p.boolean`, `p.date`, `p.datetime`, `p.enum`, `p.multiEnum`, `p.stringArray`, `p.json`, `p.phoneNumber` and `p.owner`. HubSpot field types such as `text` are not builders.
 
 ## Fix
 
@@ -17,5 +17,5 @@ plotCount: p.text('plot_count'),
 ```
 
 ```
-kalup/objects/companies.ts:5: E_UNKNOWN_BUILDER: p.text is not a builder (fix: use one of p.string, p.number, p.boolean, p.date, p.datetime, p.enum, p.multiEnum, p.stringArray, p.json) (docs: errors/E_UNKNOWN_BUILDER.md)
+hubspot/objects/companies.ts:5: E_UNKNOWN_BUILDER: p.text is not a builder (fix: use one of p.string, p.number, p.boolean, p.date, p.datetime, p.enum, p.multiEnum, p.stringArray, p.json, p.phoneNumber, p.owner) (docs: errors/E_UNKNOWN_BUILDER.md)
 ```

package/docs/errors/E_UNKNOWN_GROUP.md

@@ -17,5 +17,5 @@ plotCount: p.number('plot_count', { label: 'Plot count', group: 'orchard', field
 ```
 
 ```
-kalup/objects/companies.ts:5: E_UNKNOWN_GROUP: group 'orchard' is not in the groups of companies (fix: add orchard: { label: '...' } to the groups block) (docs: errors/E_UNKNOWN_GROUP.md)
+hubspot/objects/companies.ts:5: E_UNKNOWN_GROUP: group 'orchard' is not in the groups of companies (fix: add orchard: { label: '...' } to the groups block) (docs: errors/E_UNKNOWN_GROUP.md)
 ```