@prodshape/integration-openspec 0.1.0 → 0.3.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/index.d.ts

@@ -1,7 +1,46 @@
+import { EnumerateConsumerDocumentsOptions, ConsumerDocumentEnumeration, SddIntegrationProvider } from '@prodshape/core';
+
+/** Check if an OpenSpec workspace exists at the given root (openspec/ directory present). */
+declare function isOpenSpecWorkspace(root: string): Promise<boolean>;
+
+/** Check whether `openspec` is runnable (PATH or node_modules/.bin) with a parseable version. */
+declare function isOpenSpecCliAvailable(repoRoot?: string): Promise<boolean>;
+/**
+ * Enumerate the consumer-document population of an OpenSpec workspace.
+ *
+ * Uses `openspec list --json` to determine the current (non-archived) changes. The OpenSpec CLI
+ * excludes `openspec/changes/archive/` from `list`, so the default population is current-only.
+ * When `includeArchived` is true, archived changes under `openspec/changes/archive/` are also
+ * scanned via the filesystem (the CLI cannot address archived changes by name).
+ *
+ * For each change, the artifact files are resolved by filesystem convention: `proposal.md`,
+ * `specs/` (one or more spec files), `design.md`, `tasks.md`. The `openspec show --json` output
+ * does not include artifact paths, so convention-based resolution is the stable contract.
+ *
+ * For `openspec/specs/` (the current specs, not changes), all `.md` files are discovered.
+ *
+ * If the OpenSpec CLI is not runnable, enumeration falls back to filesystem scanning of
+ * `openspec/changes/` (excluding `archive/` unless `includeArchived`) and reports PRODUCT069:
+ * the population then rests on layout convention alone, which the gate must surface rather than
+ * silently trust.
+ */
+declare function enumerateOpenSpecDocuments(repoRoot: string, options?: EnumerateConsumerDocumentsOptions): Promise<ConsumerDocumentEnumeration>;
+/**
+ * The OpenSpec implementation of the SDD integration-provider contract.
+ * `prodshape citations verify --provider openspec` verifies the population this enumerates.
+ */
+declare const openSpecProvider: SddIntegrationProvider;
+
 /** The minimum supported OpenSpec CLI version. */
 declare const MIN_SUPPORTED_OPENSPEC = "1.0.0";
+/**
+ * The npm spec used when bootstrapping OpenSpec through npx. Pinned to the supported major:
+ * MIN_SUPPORTED_OPENSPEC guards the floor, the pin guards the ceiling, so a future OpenSpec 2.x
+ * cannot silently change what `init --tools none` does for new adopters.
+ */
+declare const OPENSPEC_NPX_SPEC = "@fission-ai/openspec@1";
 /** The PDaC authority context block injected into openspec/config.yaml `context:`. */
-declare const PDAC_CONTEXT_BLOCK = "<!-- pdac:context begin -->\nThis repository uses Product Definition as Code (PDaC). The canonical product definition lives in docs/product/model (actors, journeys, use cases, business rules, domain terms, requirements) and is the single source of truth for product behaviour. OpenSpec artifacts are downstream consumers of it, never a second source of truth.\nConsumers bind to canonical text through the PDaC Citation Contract: a citation records the target artifact id, a sha256 content digest, and an optional verification scenario anchor. Verification reports one status per citation: current, stale, tampered or unresolved.\nTo cite: run `npx prodshape inspect <ID>` to read the current digest, then `npx prodshape cite --id <ID> --digest <digest>` to emit the citation record. Place inline citations on their own line directly under the text they ground.\nThe product definition changes only through a Product Change under docs/product/changes/. OpenSpec changes never edit docs/product/model directly.\n<!-- pdac:context end -->";
+declare const PDAC_CONTEXT_BLOCK = "<!-- pdac:context begin -->\nThis repository uses Product Definition as Code (PDaC). The canonical product definition lives in docs/product/model (actors, journeys, use cases, business rules, domain terms, requirements) and is the single source of truth for product behaviour. OpenSpec artifacts are downstream consumers of it, never a second source of truth.\nConsumers bind to canonical text through the PDaC Citation Contract: a citation records the target artifact id, a sha256 content digest, and an optional verification scenario anchor. Verification reports one status per citation: current, stale, tampered or unresolved.\nTo cite: run `npx prodshape inspect <ID>` to read the current digest, then `npx prodshape cite --id <ID> --digest <digest>` to emit the citation record. Place inline citations on their own line directly under the text they ground.\nEvery current OpenSpec document (proposal, specs, design, tasks and openspec/specs/) has exactly one effective scope state: bound (it carries at least one citation, or declares `pdac-scope: cited`), exempt (a human declared `pdac-scope: none` because the document has no product-semantic dependency), or unclassified (neither declared \u2014 a verification failure). Binding and exemption are human declarations: never declare `pdac-scope: none` merely because citations are missing, and a document declared `pdac-scope: cited` with zero citations fails. Verify with `npx prodshape citations verify --provider openspec`: it enumerates the expected current document population (archived changes excluded by default), so zero discovered citations is a set of failures, never a pass.\nThe accepted Product Definition changes only through this lifecycle: propose a Product Change under docs/product/changes/, validate its overlay while the baseline remains untouched, obtain human product approval, apply explicitly on a working branch, review the applied result in a pull request, and accept the resulting baseline by human merge. A Product Change is not a pull request. Apply is not acceptance, and neither apply nor merge attests implementation, verification, release or deployment. OpenSpec changes never edit docs/product/model directly. Product-definition work and implementation work have independent cadence: an OpenSpec change may share a pull request with an applied Product Change or follow an accepted definition later, but it remains a downstream implementation concern and never supplies Product Change status.\n<!-- pdac:context end -->";
 /** The PDaC citation rules injected per artifact into openspec/config.yaml `rules:`. */
 declare const PDAC_RULES: Record<string, string[]>;
 /** The PDaC operation guidance injected into openspec/config.yaml `operations:`. */
@@ -13,6 +52,17 @@ declare const PDAC_OPERATIONS: {
         guidance: string[];
     };
 };
+/**
+ * The exact strings PDaC injected into openspec/config.yaml, recorded so a later update can
+ * remove entries whose wording has since changed instead of appending duplicates alongside them.
+ * The context block needs no record: its sentinels already identify it in place.
+ */
+interface ManagedStrings {
+    rules: Record<string, string[]>;
+    operations: Record<string, string[]>;
+}
+/** The managed strings the current PDaC guidance injects. */
+declare function currentManagedStrings(): ManagedStrings;
 /** Metadata recorded under .product/integrations/openspec.json. */
 interface OpenSpecIntegrationMeta {
     provider: 'openspec';
@@ -20,15 +70,56 @@ interface OpenSpecIntegrationMeta {
     openspecVersion: string;
     installedAt: string;
     configPath: string;
+    /** Absent in metadata written before the CI example existed; `integration update` adds it. */
+    ciExamplePath?: string;
+    /** Absent in metadata written before the field existed; treated as the current guidance. */
+    managed?: ManagedStrings;
 }
-/** Detect the installed OpenSpec CLI version by running `openspec --version`. */
-declare function detectOpenSpecVersion(): Promise<{
+/** The repository-relative path of the integration metadata file, for callers that probe it. */
+declare const OPENSPEC_META_RELATIVE = ".product/integrations/openspec.json";
+/** The repository-relative path of the installed CI-ready example workflow. */
+declare const OPENSPEC_CI_EXAMPLE_RELATIVE = ".product/integrations/openspec.ci.yml";
+/** The exact provider-aware verification command the integration stands behind. */
+declare const OPENSPEC_VERIFY_COMMAND = "npx prodshape citations verify --provider openspec";
+/**
+ * Render the CI-ready example workflow installed at {@link OPENSPEC_CI_EXAMPLE_RELATIVE}.
+ *
+ * The gate always blocks unresolved citations, tampered embedded projections, unclassified
+ * current documents and bound documents with zero citations. Stale citations follow the
+ * repository's configured warning policy (`validation.warnings-as-errors` in
+ * `.product/config.yaml`); the example never changes that policy, but it states explicitly what
+ * the repository's current choice means and how to escalate it, so the blocking behaviour is a
+ * deliberate decision rather than a silent default.
+ */
+declare function renderCiExample(options: {
+    warningsAsErrors: boolean;
+}): string;
+/**
+ * Detect the installed OpenSpec CLI version by running `openspec --version`. When a repository
+ * root is given, its node_modules/.bin is consulted first, so a devDependency install counts.
+ */
+declare function detectOpenSpecVersion(root?: string): Promise<{
     version: string;
 } | {
     error: string;
 }>;
-/** Check if an OpenSpec workspace exists at the given root (openspec/ directory present). */
-declare function isOpenSpecWorkspace(root: string): Promise<boolean>;
+/**
+ * Create an OpenSpec workspace at the root. Uses the installed CLI when one is on PATH (or in
+ * node_modules/.bin); otherwise runs the pinned OpenSpec major through npx, which downloads
+ * nothing permanent and never mutates the global environment. `--tools none` keeps the
+ * framework's own initializer non-interactive.
+ *
+ * Returns the CLI version that ran and whether it came through npx, so callers can pass the
+ * version on to `addOpenSpecIntegration` (nothing may be on PATH afterwards) and recommend a
+ * permanent install.
+ */
+declare function bootstrapOpenSpecWorkspace(root: string): Promise<{
+    version: string;
+    viaNpx: boolean;
+    command: string;
+}>;
+/** Check if the OpenSpec integration is installed (its metadata file is present). */
+declare function isOpenSpecIntegrationInstalled(root: string): Promise<boolean>;
 /** Read and parse the existing openspec/config.yaml, or null if it does not exist. */
 declare function readOpenSpecConfig(root: string): Promise<Record<string, unknown> | null>;
 /**
@@ -39,13 +130,16 @@ declare function readOpenSpecConfig(root: string): Promise<Record<string, unknow
  *   (idempotent); otherwise the PDaC block is appended after a separator. User-authored context
  *   lines are never lost.
  * - `rules`: for each PDaC artifact (proposal, specs, design, tasks), PDaC rules are appended to
- *   existing rules, deduplicating identical entries.
- * - `operations`: PDaC apply/archive guidance is appended to existing guidance, deduplicating.
+ *   existing rules, deduplicating identical entries. Entries recorded as previously managed whose
+ *   wording is no longer current are removed first, so a guidance change replaces the old string
+ *   instead of accumulating next to it. User-authored entries are never removed.
+ * - `operations`: PDaC apply/archive guidance is appended to existing guidance, deduplicating,
+ *   with the same previously-managed replacement.
  * - Any other fields (githubCopilot, etc.) are preserved untouched.
  *
  * Returns the merged config and a list of human-readable change descriptions.
  */
-declare function mergeConfig(existing: Record<string, unknown> | null): {
+declare function mergeConfig(existing: Record<string, unknown> | null, previouslyManaged?: ManagedStrings): {
     config: Record<string, unknown>;
     changes: string[];
 };
@@ -55,9 +149,12 @@ declare function serializeConfig(config: Record<string, unknown>): string;
  * Add the OpenSpec integration to a repository.
  *
  * - Detects the OpenSpec CLI version; rejects if not found or below MIN_SUPPORTED_OPENSPEC.
+ *   A caller that already ran the CLI (the init bootstrap) can pass `cliVersion` to skip the
+ *   probe: after an npx bootstrap nothing is on PATH, yet the version is known.
  * - Requires an existing `openspec/` workspace (run `openspec init` first).
  * - Merges PDaC guidance into `openspec/config.yaml`, preserving existing user configuration.
- * - Records metadata under `.product/integrations/openspec.json`.
+ * - Records metadata under `.product/integrations/openspec.json`, including the exact strings
+ *   injected, so a later update replaces outdated PDaC entries instead of accumulating them.
  * - Idempotent: running twice produces the same result.
  * - `--dry-run` reports what would change without writing.
  * - `--force` re-merges even if the PDaC block is already present (useful after a PDaC upgrade).
@@ -65,6 +162,12 @@ declare function serializeConfig(config: Record<string, unknown>): string;
 declare function addOpenSpecIntegration(root: string, options?: {
     force?: boolean;
     dryRun?: boolean;
+    cliVersion?: string;
+    /**
+     * The repository's configured `validation.warnings-as-errors` policy, reflected verbatim in
+     * the installed CI example so its blocking behaviour is stated, never silently changed.
+     */
+    warningsAsErrors?: boolean;
 }): Promise<{
     written: string[];
     changes: string[];
@@ -77,6 +180,7 @@ declare function addOpenSpecIntegration(root: string, options?: {
 declare function updateOpenSpecIntegration(root: string, options?: {
     force?: boolean;
     dryRun?: boolean;
+    warningsAsErrors?: boolean;
 }): Promise<{
     written: string[];
     changes: string[];
@@ -112,4 +216,4 @@ declare function removeOpenSpecIntegration(root: string, options?: {
     removed: string[];
 }>;
 
-export { MIN_SUPPORTED_OPENSPEC, type OpenSpecIntegrationMeta, PDAC_CONTEXT_BLOCK, PDAC_OPERATIONS, PDAC_RULES, addOpenSpecIntegration, checkOpenSpecIntegration, detectOpenSpecVersion, isOpenSpecWorkspace, mergeConfig, readOpenSpecConfig, removeOpenSpecIntegration, serializeConfig, updateOpenSpecIntegration };
+export { MIN_SUPPORTED_OPENSPEC, type ManagedStrings, OPENSPEC_CI_EXAMPLE_RELATIVE, OPENSPEC_META_RELATIVE, OPENSPEC_NPX_SPEC, OPENSPEC_VERIFY_COMMAND, type OpenSpecIntegrationMeta, PDAC_CONTEXT_BLOCK, PDAC_OPERATIONS, PDAC_RULES, addOpenSpecIntegration, bootstrapOpenSpecWorkspace, checkOpenSpecIntegration, currentManagedStrings, detectOpenSpecVersion, enumerateOpenSpecDocuments, isOpenSpecCliAvailable, isOpenSpecIntegrationInstalled, isOpenSpecWorkspace, mergeConfig, openSpecProvider, readOpenSpecConfig, removeOpenSpecIntegration, renderCiExample, serializeConfig, updateOpenSpecIntegration };