kalup 0.1.1 → 0.2.0

package/dist/commands.d.mts

@@ -1,4 +1,4 @@
-import { n as Prompter, r as Result, t as Handler } from "./context-D10Syqfd.mjs";
+import { n as Prompter, r as Result, t as Handler } from "./context-8pARDYRR.mjs";
 import { Command } from "@oclif/core";
 //#region src/host/commands.d.ts
 /**
@@ -12,6 +12,8 @@ export declare abstract class KalupCommand extends Command {
   };
   /** Stops cleanly on SIGINT or SIGTERM through `signal`. Any other command keeps the default: the signal ends it. */
   static interruptible: boolean;
+  /** Accepts `--out` with no value, as `outDefault`. oclif has no flag whose value is optional. */
+  static bareOut: boolean;
   cwd: string;
   progress: ((line: string) => void) | undefined;
   prompt: Prompter | undefined;
@@ -26,6 +28,7 @@ export declare class InitCommand extends KalupCommand {
     portal: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     objects: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     target: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    dir: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
   };
   static examples: string[];
   run(): Promise<Result>;
@@ -86,6 +89,7 @@ export declare class CompareCommand extends KalupCommand {
 }
 export declare class PlanCommand extends KalupCommand {
   static summary: string;
+  static bareOut: boolean;
   static flags: {
     target: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     out: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands.mjs

@@ -1,2 +1,2 @@
-import { _ as TargetRebindCommand, a as CompareCommand, c as InitCommand, d as PlanCommand, f as PullCommand, g as StatusCommand, h as StateRebuildCommand, i as COMMANDS, l as IrCommand, m as SnapshotCommand, n as ApplyCommand, o as DocsCommand, p as RmCommand, r as BlueprintUpgradeCommand, s as FmtCommand, t as AddCommand, u as KalupCommand, v as ValidateCommand } from "./commands-BpQ20pA7.mjs";
+import { _ as TargetRebindCommand, a as CompareCommand, c as InitCommand, d as PlanCommand, f as PullCommand, g as StatusCommand, h as StateRebuildCommand, i as COMMANDS, l as IrCommand, m as SnapshotCommand, n as ApplyCommand, o as DocsCommand, p as RmCommand, r as BlueprintUpgradeCommand, s as FmtCommand, t as AddCommand, u as KalupCommand, v as ValidateCommand } from "./commands-Bk1w1oup.mjs";
 export { AddCommand, ApplyCommand, BlueprintUpgradeCommand, COMMANDS, CompareCommand, DocsCommand, FmtCommand, InitCommand, IrCommand, KalupCommand, PlanCommand, PullCommand, RmCommand, SnapshotCommand, StateRebuildCommand, StatusCommand, TargetRebindCommand, ValidateCommand };

package/dist/{context-D10Syqfd.d.mts → context-8pARDYRR.d.mts}

@@ -1,5 +1,6 @@
 import "@kalup/core";
 //#region ../engine/dist/index.d.mts
+//#endregion
 //#region src/issues.d.ts
 declare const issues: {
   E_ACCEPT_UNMATCHED: {
@@ -233,28 +234,48 @@ declare const issues: {
       output: string[];
     };
   };
-  E_DUPLICATE_ADDRESS: {
+  E_DEFINITION_FIELD: {
     exit: string;
     title: string;
     summary: string;
     when: string[];
     fix: string[];
     example: {
+      config: string[];
       output: string[];
     };
   };
-  E_DUPLICATE_ALIAS: {
+  E_DIR_AMBIGUOUS: {
     exit: string;
     title: string;
     summary: string;
     when: string[];
     fix: string[];
     example: {
-      config: string[];
       output: string[];
     };
   };
-  E_DUPLICATE_KEY: {
+  E_DIR_IN_USE: {
+    exit: string;
+    title: string;
+    summary: string;
+    when: string[];
+    fix: string[];
+    example: {
+      output: string[];
+    };
+  };
+  E_DUPLICATE_ADDRESS: {
+    exit: string;
+    title: string;
+    summary: string;
+    when: string[];
+    fix: string[];
+    example: {
+      output: string[];
+    };
+  };
+  E_DUPLICATE_ALIAS: {
     exit: string;
     title: string;
     summary: string;
@@ -265,7 +286,7 @@ declare const issues: {
       output: string[];
     };
   };
-  E_DUPLICATE_OPTION: {
+  E_DUPLICATE_KEY: {
     exit: string;
     title: string;
     summary: string;
@@ -276,7 +297,7 @@ declare const issues: {
       output: string[];
     };
   };
-  E_DUPLICATE_PORTAL: {
+  E_DUPLICATE_OPTION: {
     exit: string;
     title: string;
     summary: string;
@@ -287,13 +308,14 @@ declare const issues: {
       output: string[];
     };
   };
-  E_FIRST_PULL: {
+  E_DUPLICATE_PORTAL: {
     exit: string;
     title: string;
     summary: string;
     when: string[];
     fix: string[];
     example: {
+      config: string[];
       output: string[];
     };
   };
@@ -484,6 +506,16 @@ declare const issues: {
       output: string[];
     };
   };
+  E_PENDING_TARGET: {
+    exit: string;
+    title: string;
+    summary: string;
+    when: string[];
+    fix: string[];
+    example: {
+      output: string[];
+    };
+  };
   E_PLAN_DELETE: {
     exit: string;
     title: string;
@@ -1044,6 +1076,16 @@ declare const issues: {
       output: string[];
     };
   };
+  W_LEGACY_DIR: {
+    exit: string;
+    title: string;
+    summary: string;
+    when: string[];
+    fix: string[];
+    example: {
+      output: string[];
+    };
+  };
   W_LIMIT_HEADROOM: {
     exit: string;
     title: string;
@@ -1084,6 +1126,17 @@ declare const issues: {
       output: string[];
     };
   };
+  W_PENDING_TARGET: {
+    exit: string;
+    title: string;
+    summary: string;
+    when: string[];
+    fix: string[];
+    example: {
+      config: string[];
+      output: string[];
+    };
+  };
   W_PIN_EXPIRES: {
     exit: string;
     title: string;
@@ -1124,6 +1177,16 @@ declare const issues: {
       output: string[];
     };
   };
+  W_STATE_NOT_MOVED: {
+    exit: string;
+    title: string;
+    summary: string;
+    when: string[];
+    fix: string[];
+    example: {
+      output: string[];
+    };
+  };
   W_UNADDRESSABLE_NAME: {
     exit: string;
     title: string;
@@ -1207,6 +1270,8 @@ interface Flags {
   /** `--approve <writesHash>`: a reviewed CI job's approval of a saved plan. */
   approve?: string;
   check: boolean;
+  /** `init --dir <path>`: the folder for the object files. */
+  dir?: string;
   discover: boolean;
   /** `add` and `blueprint upgrade --dry-run`: report what would change and write nothing. */
   dryRun: boolean;
@@ -1214,6 +1279,8 @@ interface Flags {
   objects?: string;
   only?: string;
   out?: string;
+  /** `plan --out` with no file: write the plan under .kalup/plans/. */
+  outDefault?: boolean;
   portal?: string;
   /** `add --prefix <p>`: the prefix for one add, over config's `prefix`. */
   prefix?: string;

package/dist/{host-CcBOCkff.mjs → host-BoqS00po.mjs}

@@ -1,4 +1,4 @@
-import { A as sanitize, C as usageError, D as disclaimer, E as bin, O as escapeJson, S as versionText, T as KalupError, b as formats, k as exitCodes, u as KalupCommand, w as IssueError, x as version, y as PATH_MAX } from "./commands-BpQ20pA7.mjs";
+import { A as sanitize, C as usageError, D as disclaimer, E as bin, O as escapeJson, S as versionText, T as KalupError, b as formats, k as exitCodes, u as KalupCommand, w as IssueError, x as version, y as PATH_MAX } from "./commands-Bk1w1oup.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";

package/dist/host.d.mts

@@ -1,4 +1,4 @@
-import { i as ExitCode, n as Prompter, r as Result } from "./context-D10Syqfd.mjs";
+import { i as ExitCode, n as Prompter, r as Result } from "./context-8pARDYRR.mjs";
 //#region src/host/host.d.ts
 interface Out {
   write: (text: string) => unknown;

package/dist/host.mjs

@@ -1,2 +1,2 @@
-import { n as isInteractive, r as run, t as execute } from "./host-CcBOCkff.mjs";
+import { n as isInteractive, r as run, t as execute } from "./host-BoqS00po.mjs";
 export { execute, isInteractive, run };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as isInteractive, r as run } from "./host-CcBOCkff.mjs";
+import { n as isInteractive, r as run } from "./host-BoqS00po.mjs";
 //#region src/index.ts
 process.exitCode = await run(process.argv.slice(2), {
 	cwd: process.cwd(),

package/dist/schemas/blueprint-1.schema.json

@@ -84,7 +84,7 @@
       "properties": {
         "label": { "type": "string" },
         "group": { "$ref": "#/$defs/ref" },
-        "type": { "enum": ["string", "number", "bool", "date", "datetime", "enumeration"] },
+        "type": { "enum": ["string", "number", "bool", "date", "datetime", "enumeration", "phone_number"] },
         "fieldType": {
           "enum": [
             "text",
@@ -96,13 +96,38 @@
             "select",
             "radio",
             "checkbox",
-            "date"
+            "date",
+            "html",
+            "calculation_equation"
           ]
         },
         "description": { "type": "string" },
         "options": { "type": "array", "items": { "$ref": "#/$defs/option" } },
         "hasUniqueValue": { "type": "boolean" },
-        "formField": { "type": "boolean" }
+        "formField": { "type": "boolean" },
+        "hidden": { "type": "boolean" },
+        "displayOrder": { "type": "integer", "minimum": -1 },
+        "numberDisplayHint": {
+          "enum": ["currency", "duration", "formatted", "percentage", "probability", "unformatted"]
+        },
+        "showCurrencySymbol": { "type": "boolean" },
+        "currencyPropertyName": { "type": "string" },
+        "textDisplayHint": {
+          "enum": [
+            "domain_name",
+            "email",
+            "ip_address",
+            "multi_line",
+            "phone_number",
+            "physical_address",
+            "postal_code",
+            "unformatted_single_line"
+          ]
+        },
+        "calculationFormula": { "type": "string" },
+        "dataSensitivity": { "enum": ["non_sensitive", "sensitive", "highly_sensitive"] },
+        "externalOptions": { "const": true },
+        "referencedObjectType": { "const": "OWNER" }
       },
       "additionalProperties": false
     },
@@ -128,7 +153,20 @@
       "type": "object",
       "properties": {
         "key": { "type": "string", "pattern": "^[A-Za-z_$][A-Za-z0-9_$]*$" },
-        "codec": { "enum": ["string", "number", "boolean", "date", "datetime", "enum", "multiEnum", "stringArray"] },
+        "codec": {
+          "enum": [
+            "string",
+            "number",
+            "boolean",
+            "date",
+            "datetime",
+            "enum",
+            "multiEnum",
+            "stringArray",
+            "phoneNumber",
+            "owner"
+          ]
+        },
         "aliases": { "type": "object", "additionalProperties": { "type": "string" } },
         "required": { "type": "boolean" },
         "readonly": { "type": "boolean" },

package/dist/schemas/blueprints-lock-1.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://kalup.dev/schemas/blueprints-lock-1.schema.json",
   "title": "Kalup blueprints lock, version 1",
-  "description": "kalup/blueprints.lock.json, written by `kalup add` and `kalup blueprint upgrade`, never by hand. Records where each blueprint came from, the stored original upgrades merge against, and which config resources it provides. Closed at every level.",
+  "description": "blueprints.lock.json in the folder of object files (hubspot/ by default), written by `kalup add` and `kalup blueprint upgrade`, never by hand. Records where each blueprint came from, the stored original upgrades merge against, and which config resources it provides. Closed at every level.",
   "type": "object",
   "required": ["lockVersion", "blueprints", "sources"],
   "properties": {
@@ -44,7 +44,7 @@
         "hash": { "$ref": "#/$defs/hash" },
         "prefix": { "type": "string", "pattern": "^([a-z][a-z0-9_]*)?$" },
         "original": {
-          "description": "The stored original, kalup/.blueprints/<name with / as -->@<version>.json.",
+          "description": "The stored original, <dir>/.blueprints/<name with / as -->@<version>.json.",
           "type": "string"
         },
         "resources": {

package/dist/schemas/ir-1.schema.json

@@ -102,7 +102,7 @@
       "properties": {
         "label": { "type": "string" },
         "group": { "$ref": "#/$defs/ref" },
-        "type": { "enum": ["string", "number", "bool", "date", "datetime", "enumeration"] },
+        "type": { "enum": ["string", "number", "bool", "date", "datetime", "enumeration", "phone_number"] },
         "fieldType": {
           "enum": [
             "text",
@@ -114,13 +114,38 @@
             "select",
             "radio",
             "checkbox",
-            "date"
+            "date",
+            "html",
+            "calculation_equation"
           ]
         },
         "description": { "type": "string" },
         "options": { "type": "array", "items": { "$ref": "#/$defs/option" } },
         "hasUniqueValue": { "type": "boolean" },
-        "formField": { "type": "boolean" }
+        "formField": { "type": "boolean" },
+        "hidden": { "type": "boolean" },
+        "displayOrder": { "type": "integer", "minimum": -1 },
+        "numberDisplayHint": {
+          "enum": ["currency", "duration", "formatted", "percentage", "probability", "unformatted"]
+        },
+        "showCurrencySymbol": { "type": "boolean" },
+        "currencyPropertyName": { "type": "string" },
+        "textDisplayHint": {
+          "enum": [
+            "domain_name",
+            "email",
+            "ip_address",
+            "multi_line",
+            "phone_number",
+            "physical_address",
+            "postal_code",
+            "unformatted_single_line"
+          ]
+        },
+        "calculationFormula": { "type": "string" },
+        "dataSensitivity": { "enum": ["non_sensitive", "sensitive", "highly_sensitive"] },
+        "externalOptions": { "const": true },
+        "referencedObjectType": { "const": "OWNER" }
       },
       "additionalProperties": false
     },
@@ -166,7 +191,19 @@
       "properties": {
         "key": { "type": "string" },
         "codec": {
-          "enum": ["string", "number", "boolean", "date", "datetime", "enum", "multiEnum", "stringArray", "json"]
+          "enum": [
+            "string",
+            "number",
+            "boolean",
+            "date",
+            "datetime",
+            "enum",
+            "multiEnum",
+            "stringArray",
+            "json",
+            "phoneNumber",
+            "owner"
+          ]
         },
         "aliases": { "type": "object", "additionalProperties": { "type": "string" } },
         "required": { "type": "boolean" },
@@ -188,7 +225,7 @@
       "additionalProperties": false
     },
     "provenance": {
-      "description": "Merged from kalup/blueprints.lock.json by the loader. Absent means authored by hand.",
+      "description": "Merged from blueprints.lock.json in the folder of object files by the loader. Absent means authored by hand.",
       "type": "object",
       "required": ["blueprint", "version", "sourceAddress", "prefix", "hash"],
       "properties": {

package/dist/schemas/plan-1.schema.json

@@ -689,7 +689,7 @@
       "additionalProperties": false
     },
     "held": {
-      "description": "A unit reported and not written, with the command that takes the portal side: a pull, or pull --accept. resolve is left out when no pull takes the portal side: the resource names a portal name a name override shadows (shadowed:<name>), or a property is outside its object's pull scope, holds a type or fieldType its builder does not take, or sits in a portal group kalup/removed.ts names; in those three cases a note on the same unit says why.",
+      "description": "A unit reported and not written, with the command that takes the portal side: a pull, or pull --accept. resolve is left out when no pull takes the portal side: the resource names a portal name a name override shadows (shadowed:<name>), or a property holds a type or fieldType its builder does not take, or sits in a portal group removed.ts names; in those cases a note on the same unit says why.",
       "type": "object",
       "required": ["unit", "class", "config", "live"],
       "properties": {

package/docs/apply.md

@@ -1,6 +1,6 @@
 # Apply
 
-`kalup apply <plan-file> [--yes | --approve <writesHash>]` applies a plan saved by `kalup plan --out` to the target it names. `kalup apply [--target <name>] [--take config <selector>] [--yes]` plans an unprotected target now and applies that plan through the same checks. Apply writes property groups and properties, on custom objects too, and never a custom object schema.
+`kalup apply <plan-file> [--yes | --approve <writesHash>]` applies a plan saved by `kalup plan --out` to the target it names. `kalup apply [--target <name>] [--take config <selector>] [--yes]` plans the target now and applies that plan through the same checks: at a terminal it prints the whole plan first, as `plan` does, then asks. Apply writes property groups and properties, on custom objects too, and never a custom object schema.
 
 This page is the reference. For the walk-through with examples, see [kalup apply](https://kalup.dev/docs/commands/apply) on the website.
 
@@ -12,7 +12,7 @@ A plan with any effect (a write, adoption, release, delete or state-only update)
 - **`--yes`**: an unprotected target, no step Kalup derives as risky or destructive, at most the target's `yesLimit` (default 25; `0` turns `--yes` off) writes, adoptions and releases. It trusts the file once its digest matches, never past the risk or delete rules.
 - **`--approve <writesHash>`**: a reviewed CI job. The digest must equal the file's recomputed `writesHash` (`E_APPROVE_MISMATCH`), and the target must name its own `credentials.write`, read from the process environment, with no `.env` defining it (`E_APPROVE_CREDENTIAL`). It covers protected targets and risky steps, and shows only that the writes equal a reviewed digest, not that a review happened. A write key exported in a workstation shell satisfies it too, so keep that key only in CI. Agents never pass it.
 
-Every delete, and every option removal takeover asks for, needs the person at a terminal. Otherwise apply stops with `E_APPROVAL_REQUIRED`, exit 4, printing the command. A protected target accepts only a saved plan (`E_PROTECTED_SAVED_PLAN`).
+Every delete, and every option removal takeover asks for, needs the person at a terminal. Otherwise apply stops with `E_APPROVAL_REQUIRED`, exit 4, printing the command. Without a plan file, a protected target applies only for the person at a terminal; with no terminal apply stops after the portal guard, before it plans (`E_PROTECTED_SAVED_PLAN`, exit 4). In CI, save the plan with `kalup plan --out` and apply that file after review.
 
 The terminal question stops an over-eager agent, not a hostile one: anything with a shell on the machine can read its keys.
 
@@ -25,7 +25,7 @@ Before any write, in order:
 3. The write key (`credentials.write`, else the read key) passes the portal guard. Every request, reads included, uses it.
 4. The policy equals the plan's: `protected`, `drift`, `adopt`, `allowDestroy`, `yesLimit` and the objects in takeover (`E_POLICY_CHANGED`); each step's API version is current and unexpired, and the normalizer versions match (`E_PLAN_VERSION`).
 5. Every step but a release is on an object `kalup.config.ts` declares, the name bindings match the target's name overrides, and no two steps but releases resolve to one portal resource (`E_BINDING_CHANGED`).
-6. Each delete has a `destroy` tombstone in `kalup/removed.ts` or takeover's leave (takeover mode, in the pull scope, not excluded), is gone from config, and no address in config names its portal resource, read as data (`E_PLAN_DELETE`). The object files also tell takeover's option removals from config's own.
+6. Each delete has a `destroy` tombstone in `hubspot/removed.ts` or takeover's leave (takeover mode, in the pull scope, not excluded), is gone from config, and no address in config names its portal resource, read as data (`E_PLAN_DELETE`). The object files also tell takeover's option removals from config's own.
 7. Approval, then the portal lock (`E_LOCKED`).
 8. State: a plan already applied with outcome `done` exits 0 ("Already applied"); otherwise lineage and serial equal the plan's (`E_STATE_CHANGED`).
 9. A fresh read of each object the plan changes, and of the schemas list for a custom object (`E_INCOMPLETE` on a 403, `E_BINDING_CHANGED` for another type ID). Every `expect` must hold (`E_PLAN_STALE`), a delete's covering each field its base holds. Kalup derives each step's risk, labels and blocked status again (`E_PLAN_RISK` when the plan states less); a takeover removal needs `allowDestroy`, and never takes a HubSpot-defined property.

package/docs/blueprints.md

@@ -39,8 +39,8 @@ Anything else is `E_BLUEPRINT_SCHEMA`. The schema ships in `kalup` as `kalup/sch
 
 1. The bytes are hashed (`sha256:`), parsed as JSON and checked. The prefix is applied (below).
 2. A new resource is added. One config already has with the same definition and binding is recorded under the blueprint, not rewritten. Any other difference is `E_BLUEPRINT_COLLISION`, listing the differing units; so is a `.managed(false)` entry, or an address another blueprint provides.
-3. Resources go into the export that holds their object, or a new `kalup/objects/<object>.ts` for a standard object. A custom object must already be in config (`E_BLUEPRINT_REQUIRES`). An object missing from `objects` in `kalup.config.ts` is added as `{}`.
-4. The lock entry goes to `kalup/blueprints.lock.json`, and the bytes, unchanged, to `kalup/.blueprints/<name with / as -->@<version>.json`. `.gitattributes` gets `kalup/.blueprints/** -text`, so git never changes their line endings.
+3. Resources go into the export that holds their object, or a new `hubspot/objects/<object>.ts` for a standard object. A custom object must already be in config (`E_BLUEPRINT_REQUIRES`). An object missing from `objects` in `kalup.config.ts` is added as `{}`.
+4. The lock entry goes to `hubspot/blueprints.lock.json`, and the bytes, unchanged, to `hubspot/.blueprints/<name with / as -->@<version>.json`. `.gitattributes` gets `hubspot/.blueprints/** -text`, so git never changes their line endings.
 
 The project as add would leave it is validated first: any issue, such as a binding key another property uses, is exit 3. Files are copied to `.kalup/history/`, then written as one change (`E_PROJECT_WRITE` restores them on a failure).
 
@@ -66,7 +66,7 @@ A field a version owns for the first time, where the portal holds another value,
 
 ## Provenance and the lock
 
-These two commands write `kalup/blueprints.lock.json`, never a person (`E_BLUEPRINT_LOCK`, exit 3). Per blueprint it records `version`, `source`, `hash`, `prefix`, `original`, `resources` (local address to blueprint address) and `held`. The loader adds `provenance` to each config resource the lock lists; `kalup ir` shows it. Commit the lock, `kalup/.blueprints/` and `.gitattributes` with the config.
+These two commands write `hubspot/blueprints.lock.json`, never a person (`E_BLUEPRINT_LOCK`, exit 3). Per blueprint it records `version`, `source`, `hash`, `prefix`, `original`, `resources` (local address to blueprint address) and `held`. The loader adds `provenance` to each config resource the lock lists; `kalup ir` shows it. Commit the lock, `hubspot/.blueprints/` and `.gitattributes` with the config.
 
 ## Integrity
 

package/docs/compare.md

@@ -27,7 +27,7 @@ The project must load and validate only when a side is `config` or a target (exi
 Every address present on either side, including properties Kalup does not write, and every config address. Each gets a status:
 
 - Equal: every unit converged. Counted, not listed.
-- `differs`: `changes[]` lists options to add or remove; `held[]` lists units that differ, `diverged` since there is no base; `notes[]` lists options only `b` holds, kept because options are additive. When `b` is a portal side, the note names the pull command that brings the option into config. `pull` does not write a resource that names a portal name a `name` override shadows (`shadowed:<name>`), so on such a resource the note says to correct or remove that override instead. Nor does it write a property outside its object's pull scope, so there the note says to add the name to `objects.<object>.include`. A snapshot does not record whether HubSpot defines a property, so on a reference `include` does not name, a snapshot's note says it may be outside the scope and gives the same advice.
+- `differs`: `changes[]` lists options to add or remove; `held[]` lists units that differ, `diverged` since there is no base; `notes[]` lists options only `b` holds, kept because options are additive. When `b` is a portal side, the note names the pull command that brings the option into config. `pull` does not write a resource that names a portal name a `name` override shadows (`shadowed:<name>`), so on such a resource the note says to correct or remove that override instead. Nor does it bring in a property the files lack that is outside its object's pull scope, so there the note says to add the name to `objects.<object>.include`; a property the files define is always in scope. A snapshot does not record whether HubSpot defines a property, so on a reference `include` does not name, a snapshot's note says it may be outside the scope and gives the same advice.
 - `only-a` or `only-b`: on one side only.
 - `unmanaged`: only a portal side holds it and the other side is config. Listed and counted, never a difference: absence never deletes.
 - `unknown`: a side could not read its object, never read it, left out a property config names because its group's name holds whitespace (`W_UNADDRESSABLE_NAME`), or a target side has a `lookup` override, since this version manages no lookup resources. `reason` says which side and why.

package/docs/config.md

@@ -1,16 +1,21 @@
 # Config files
 
-Kalup reads `kalup.config.ts` and every `.ts` file under `kalup/` except `kalup/index.ts` as data. It parses a small grammar and never runs them. The app imports the same files and runs them for types and codecs.
+Kalup reads `kalup.config.ts` and every `.ts` file in the folder of object files except its `index.ts` as data. The folder is `hubspot/` unless `dir` in `kalup.config.ts` names another, such as `dir: 'lib/config/hubspot'`; the paths below use `hubspot/`. It parses a small grammar and never runs them. The app imports the same files and runs them for types and codecs.
 
 This page is the reference. For the walk-through with examples, see [Config files](https://kalup.dev/docs/config/config-files), [kalup.config.ts](https://kalup.dev/docs/config/kalup-config) and [Property builders](https://kalup.dev/docs/config/property-builders) on the website.
 
 ## Files
 
-- `kalup.config.ts`: one `export default defineConfig({...})` and nothing after it. Fields: `name` (default: the directory name), `prefix`, `defaultTarget` (targets.md), `mode` (below), `objects` (the pull scope, pull.md) and `targets` (targets.md). A setting at a level that does not take it is `E_SETTING_LEVEL`, whose fix lists the levels that do; a value it does not take is `E_SETTING_VALUE`, with the nearest allowed one.
-- `kalup/objects/<object>.ts`: one or more `export const <Name> = defineObject('<object>', {...})` or `defineCustomObject('<name>', {...})`. The writer adds an `export type <Name>Data = ...` line after each. A file with no such export is `E_MISSING_EXPORT`.
-- `kalup/index.ts`: the barrel, written by `pull` and `fmt`. It imports each object file as `./objects/<object>.js`, which resolves under TypeScript `NodeNext`, `Node16` and `Bundler` resolution, bundlers such as Vite and Next.js, and plain Node running `tsc` output. Under `NodeNext`, import it as `./kalup/index.js`.
-- `kalup/removed.ts`: tombstones, below.
-- `kalup/pipelines/*`, and a `defineConfig` or `defineRemoved` file elsewhere under `kalup/`, are `E_UNSUPPORTED_FILE`.
+- `kalup.config.ts`: one `export default defineConfig({...})` and nothing after it. Fields: `name` (default: the name in the nearest `package.json` up to the repository root, else the directory name), `dir` (the folder of object files, relative to `kalup.config.ts` and inside the project, default `hubspot`; `E_SETTING_VALUE` otherwise), `state` (`'local'`, the default, or `'repo'`, state.md), `prefix`, `defaultTarget` (targets.md), `mode` (below), `objects` (the pull scope, pull.md) and `targets` (targets.md). A setting at a level that does not take it is `E_SETTING_LEVEL`, whose fix lists the levels that do; a value it does not take is `E_SETTING_VALUE`, with the nearest allowed one.
+- `hubspot/objects/<object>.ts`: one or more `export const <Name> = defineObject('<object>', {...})` or `defineCustomObject('<name>', {...})`. The writer adds an `export type <Name>Data = ...` line after each. A file with no such export is `E_MISSING_EXPORT`.
+- `hubspot/index.ts`: the barrel, written by `pull` and `fmt`. It imports each object file as `./objects/<object>.js`, which resolves under TypeScript `NodeNext`, `Node16` and `Bundler` resolution, bundlers such as Vite and Next.js, and plain Node running `tsc` output. Under `NodeNext`, import it as `./hubspot/index.js`.
+- `hubspot/removed.ts`: tombstones, below.
+- `hubspot/pipelines/*`, and a `defineConfig` or `defineRemoved` file elsewhere under `hubspot/`, are `E_UNSUPPORTED_FILE`.
+- `hubspot/blueprints.lock.json` and `hubspot/.blueprints/`: written by `kalup add` (blueprints.md).
+
+The folder belongs to Kalup alone: every `.ts` file in it is read as config, `pull` rewrites its `index.ts`, and `init` takes it out of the formatter's checks. Point `dir` at a folder of its own (`lib/config/hubspot`, not `lib/config` next to the app's modules); `init` refuses a folder that holds other `.ts` files (`E_DIR_IN_USE`). A 0.1 project keeps its `kalup/` folder while `dir` is unset and `hubspot/` holds no `.ts` file, with `W_LEGACY_DIR` on every command until you set `dir: 'kalup'` or move the folder. When both hold `.ts` files, every command stops with `E_DIR_AMBIGUOUS` until `dir` says which.
+
+Commit `kalup.config.ts` and the folder: the object files, `index.ts`, `removed.ts`, the blueprints lock, and `state/` only with `state: 'repo'` (state.md). Never commit `.kalup/` (local state, saved plans, journals, history, snapshots), a plan file, `.env` or any file holding a key.
 
 ## The grammar
 
@@ -29,18 +34,29 @@ Anything else is `E_NOT_DATA`.
 
 Each builder sets the HubSpot `type`, which config never states, and allows these `fieldType` values. Any other is `E_TYPE_FIELDTYPE`.
 
-- `p.string`, `p.stringArray`, `p.json`: `string`; text, textarea, file, phonenumber.
-- `p.number`: `number`; number.
-- `p.boolean`: `bool`; booleancheckbox.
+- `p.string`: `string`; text, textarea, file, phonenumber, html (rich text), calculation_equation.
+- `p.stringArray`, `p.json`: `string`; text, textarea, file, phonenumber.
+- `p.number`: `number`; number, calculation_equation.
+- `p.boolean`: `bool`; booleancheckbox, calculation_equation. Kalup creates it with the options `true` and `false`, which HubSpot requires.
 - `p.date` (`YYYY-MM-DD`) and `p.datetime` (ISO 8601): `date` and `datetime`; date.
-- `p.enum`: `enumeration`; select, radio, booleancheckbox.
+- `p.enum`: `enumeration`; select, radio, booleancheckbox, calculation_equation.
 - `p.multiEnum`: `enumeration`; checkbox.
+- `p.phoneNumber`: `phone_number`; phonenumber. The value is the text HubSpot stores.
+- `p.owner`: `enumeration`; select, radio, with options HubSpot fills from the account's users (`externalOptions: true`, `referencedObjectType: 'OWNER'`, both implied). The value is the owner ID. It takes no `options`.
 
-In the app every value can be `null`, and a blank one reads as `null`. `p.enum` gives one alias, `p.multiEnum` an alias array (`;`-separated on the wire); a stored value the options do not list reads as `Unlisted`, a branded string `set` writes back unchanged. `.strict()` makes both throw on it instead and drops `Unlisted` from the type; it needs options (`E_STRICT_WITHOUT_OPTIONS`). A bare `p.enum` reference is `Unlisted | null`. `p.stringArray` a `string[]` (split on `,` or `;`, written `,`-joined), `p.json` the validator's output. `.required()` drops `null` and makes `get` throw on a missing value. `.readonly()` removes `set` from the type. `pull` never writes `.required()`, `p.stringArray` or `p.json`, and keeps them.
+In the app every value can be `null`, and a blank one reads as `null`. `p.enum` gives one alias, `p.multiEnum` an alias array (`;`-separated on the wire); a stored value the options do not list reads as `Unlisted`, a branded string `set` writes back unchanged. `.strict()` makes both throw on it instead and drops `Unlisted` from the type; it needs options (`E_STRICT_WITHOUT_OPTIONS`). A bare `p.enum` reference is `Unlisted | null`. `p.stringArray` a `string[]` (split on `,` or `;`, written `,`-joined), `p.json` the validator's output. `.required()` drops `null` and makes `get` throw on a missing value. `.readonly()` removes `set` and `clear` from the type. `clear(bag)` writes `''`, which HubSpot reads as a clear; it does not compile on a `.required()` codec, and `set(bag, null)` leaves the bag untouched. A codec's `property` is its internal name as a literal type, and `PropertyName<typeof Company>` is the union of an object's names. `pull` never writes `.required()`, `p.stringArray` or `p.json`, and keeps them.
 
 ## Managed, reference, options-only
 
-A definition with `label`, `group` and `fieldType` is managed: the fields present are owned, and an omitted `description`, `options`, `hasUniqueValue` or `formField` belongs to the portal. `group` must name a group declared under `groups` for the same object, in any export or file (`E_UNKNOWN_GROUP`). A managed internal name starting with `hs_` is `E_HS_PREFIX`.
+A definition with `label`, `group` and `fieldType` is managed: the fields present are owned, and an omitted field belongs to the portal. The optional fields, in HubSpot's names:
+
+- `description`, `options`, `formField`, `hidden` (not shown in HubSpot), `displayOrder` (place in the group: lowest positive first, `-1` after the rest).
+- `hasUniqueValue` and `dataSensitivity` (`non_sensitive`, `sensitive`, `highly_sensitive`): set on create only. HubSpot keeps them whatever a later update says, so a difference blocks the plan with a migration.
+- On `p.number`: `numberDisplayHint` (`formatted`, `unformatted`, `currency`, `percentage`, `duration`, `probability`), `showCurrencySymbol`, and `currencyPropertyName`, which needs `showCurrencySymbol: true`.
+- On `p.string`, `p.stringArray`, `p.json` and `p.phoneNumber`: `textDisplayHint` (`unformatted_single_line`, `multi_line`, `email`, `phone_number`, `domain_name`, `ip_address`, `physical_address`, `postal_code`). HubSpot takes no value that removes a hint.
+- `calculationFormula` with `fieldType: 'calculation_equation'`, in HubSpot's formula syntax. HubSpot stores its own spelling (`a+1` as `a + 1`); write it as pull does, or plan notes the difference. A formula change is risky.
+
+A field another builder or field rules out is `E_DEFINITION_FIELD`. HubSpot ignores `dateDisplayHint`, so it is no field. `group` must name a group declared under `groups` for the same object, in any export or file (`E_UNKNOWN_GROUP`). A managed internal name starting with `hs_` is `E_HS_PREFIX`.
 
 No definition makes a reference: never created, changed or removed. `p.enum` or `p.multiEnum` with `options` and nothing else is a reference with typed options, which pull refreshes.
 
@@ -62,17 +78,17 @@ The object key is the app's name for the property. Two exports of one object usi
 
 ## Per-target definitions
 
-A target's override `definition` (targets.md) replaces each field it states there, whole, and owns it, empty values included: a property's `label`, `description`, `group`, `fieldType`, `formField`, `options` (no `as`) and lifecycle but `preventDestroy`; a group's `label`. Else `E_OVERRIDE_DEFINITION`. `pull` writes these fields into the override.
+A target's override `definition` (targets.md) replaces each field it states there, whole, and owns it, empty values included: a property's `label`, `description`, `group`, `fieldType`, `formField`, `options` (no `as`), `hidden`, `displayOrder`, the display fields, `calculationFormula` and lifecycle but `preventDestroy`; a group's `label`. Else `E_OVERRIDE_DEFINITION`. `pull` writes these fields into the override.
 
 ## Mode: addon and takeover
 
 `mode: 'addon' | 'takeover'` at the top level, under `objects.<object>`, under `targets.<target>`, or under `targets.<target>.objects.<object>`. The most specific wins, in that order from the last, and the default is `addon`: Kalup manages only what config names. A target `mode` that differs from an object's `mode` the target says nothing more about is `W_MODE_SHADOWED`.
 
-Under `takeover`, `plan` archives every custom property and group in the object's pull scope that config lacks and `kalup/removed.ts` does not name (a group only once every property in it goes, and after them), and removes enum options only the portal holds. Never a HubSpot-defined or calculated property, a kind Kalup does not write, anything an object file lists, a name `exclude` covers, or a property a custom object schema names. Every takeover removal is destructive: it needs `allowDestroy: true` on the target and a person at a terminal, and `--yes` and `--approve` never cover it. Without `allowDestroy` it is blocked, reason `policy`; after an incomplete read, reason `scope`.
+Under `takeover`, `plan` archives every custom property and group in the object's pull scope that config lacks and `hubspot/removed.ts` does not name (a group only once every property in it goes, and after them), and removes enum options only the portal holds. Never a HubSpot-defined or calculated property, a kind Kalup does not write, anything an object file lists, a name `exclude` covers, or a property a custom object schema names. Every takeover removal is destructive: it needs `allowDestroy: true` on the target and a person at a terminal, and `--yes` and `--approve` never cover it. Without `allowDestroy` it is blocked, reason `policy`; after an incomplete read, reason `scope`.
 
 ## Removed resources
 
-`kalup/removed.ts` holds `export default defineRemoved({...})`, keyed by address:
+`hubspot/removed.ts` holds `export default defineRemoved({...})`, keyed by address:
 
 ```ts
 export default defineRemoved({
@@ -85,4 +101,4 @@ export default defineRemoved({
 
 ## Canonical form
 
-`kalup fmt` validates, then rewrites `kalup.config.ts`, `kalup/removed.ts`, every object file and the barrel: groups and properties sorted by internal name, tombstones by address, fields in a fixed order, options in display order, quotes as biome writes them, 120 columns. It keeps every value you wrote, `description: ''`, `options: []`, `false` and an empty `lifecycle` included: a present field is owned. `fmt --check` lists the files it would change; `--exit-code` exits 2 then. Old files go to `.kalup/history/<timestamp>/` first; the last 20 runs are kept.
+`kalup fmt` validates, then rewrites `kalup.config.ts`, `hubspot/removed.ts`, every object file and the barrel: groups and properties sorted by internal name, tombstones by address, fields in a fixed order, options in display order, quotes as biome writes them, 120 columns. It keeps every value you wrote, `description: ''`, `options: []`, `false` and an empty `lifecycle` included: a present field is owned. `fmt --check` lists the files it would change and exits 2 when there are any. Old files go to `.kalup/history/<timestamp>/` first; the last 20 runs are kept.

package/docs/errors/E_BAD_CHAIN.md

@@ -17,5 +17,5 @@ plotCount: p.number('plot_count').optional(),
 ```
 
 ```
-kalup/objects/companies.ts:5: E_BAD_CHAIN: .optional() is not a chain call (fix: use .strict(), .required(), .readonly() or .managed(false)) (docs: errors/E_BAD_CHAIN.md)
+hubspot/objects/companies.ts:5: E_BAD_CHAIN: .optional() is not a chain call (fix: use .strict(), .required(), .readonly() or .managed(false)) (docs: errors/E_BAD_CHAIN.md)
 ```

package/docs/errors/E_BIOME_CONFIG.md

@@ -4,11 +4,11 @@
 
 ## When
 
-`init` adds `!kalup`, `!kalup.config.ts` and `!.kalup` to `files.includes` in `biome.json`, so it reads that file before it writes anything. Biome reads `biome.json` as plain JSON, so a comment in it is also this error. A `biome.jsonc` that does not parse is not an error: `init` leaves it alone and prints a note.
+`init` adds `!hubspot`, `!kalup.config.ts` and `!.kalup` (with the path from the config to the project in a monorepo) to `files.includes` in the nearest `biome.json` from the project up to the repository root, so it reads that file before it writes anything. Biome reads `biome.json` as plain JSON, so a comment in it is also this error. A `biome.jsonc` that does not parse is not an error: `init` leaves it alone and prints a note.
 
 ## Fix
 
-Fix the JSON in `biome.json` (a trailing comma or a comment is the usual cause), then run `npx --no-install kalup init --portal <id>` again.
+Fix the JSON in `biome.json` (a trailing comma or a comment is the usual cause), then run `npx --no-install kalup init` again.
 
 ## Example
 

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)
 ```