@bovinphang/craft-common 1.0.1 → 2.0.0

package/skills/cc-go-project-standard/references/common/engineering-practices.sources.json

@@ -0,0 +1,377 @@
+{
+  "schemaVersion": 1,
+  "sources": [
+    {
+      "id": "google-review",
+      "publisher": "Google",
+      "title": "Code review standard",
+      "url": "https://google.github.io/eng-practices/review/reviewer/standard.html",
+      "section": "Engineering principles and code health",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guidance; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Use evidence and project standards; personal preference alone is not a blocker."
+    },
+    {
+      "id": "ms-playbook",
+      "publisher": "Microsoft ISE",
+      "title": "Test planning",
+      "url": "https://microsoft.github.io/code-with-engineering-playbook/automated-testing/test-planning/",
+      "section": "Risk, test scope and responsibilities",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living ISE playbook; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Team practice, not a company-wide mandate; retain existing tools."
+    },
+    {
+      "id": "ms-faults",
+      "publisher": "Microsoft ISE",
+      "title": "Fault injection testing",
+      "url": "https://microsoft.github.io/code-with-engineering-playbook/automated-testing/fault-injection-testing/",
+      "section": "Controlled failure and observations",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living ISE playbook; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Run scoped, controlled failures; do not infer production reliability from a small example."
+    },
+    {
+      "id": "google-ts",
+      "publisher": "Google",
+      "title": "TS/JS style guide",
+      "url": "https://google.github.io/styleguide/tsguide.html",
+      "section": "Environment caveat; types and exceptions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Google explicitly notes internal constraints differ; no blanket ban overriding a justified project convention."
+    },
+    {
+      "id": "typescript-publishing",
+      "publisher": "TypeScript",
+      "title": "Publishing declaration files",
+      "url": "https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html",
+      "section": "Types and declaration dependencies",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living handbook; check installed compiler/module resolution",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Validate the actual packed consumer; do not upgrade compiler or module mode on this basis."
+    },
+    {
+      "id": "rust-api",
+      "publisher": "Rust library team",
+      "title": "Rust API Guidelines",
+      "url": "https://rust-lang.github.io/api-guidelines/",
+      "section": "Type safety, dependability and future proofing",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living recommendations; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Guidance rather than language law; preserve edition and MSRV."
+    },
+    {
+      "id": "tokio-join",
+      "publisher": "Tokio project",
+      "title": "JoinHandle",
+      "url": "https://docs.rs/tokio/latest/tokio/task/struct.JoinHandle.html",
+      "section": "Drop, abort and completion",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed 1.54.1; project runtime/version determines applicability",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Tokio-specific mechanics only when Tokio is already used; no new runtime dependency."
+    },
+    {
+      "id": "uber-go",
+      "publisher": "Uber",
+      "title": "Go Style Guide",
+      "url": "https://github.com/uber-go/guide/blob/master/style.md",
+      "section": "Errors, interfaces and goroutine lifetime",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living master; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Do not import Uber dependencies or turn buffer-size style into a correctness theorem."
+    },
+    {
+      "id": "go-context",
+      "publisher": "Go project",
+      "title": "context package",
+      "url": "https://pkg.go.dev/context",
+      "section": "Cancellation propagation and ownership",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Standard library; check owning go.mod/toolchain",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "A cancellation signal alone does not confirm worker exit."
+    },
+    {
+      "id": "google-java",
+      "publisher": "Google",
+      "title": "Java Style Guide",
+      "url": "https://google.github.io/styleguide/javaguide.html",
+      "section": "Source structure and exception handling",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public style; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Naming/layout follows local standard; style is distinct from runtime correctness."
+    },
+    {
+      "id": "oracle-resources",
+      "publisher": "Oracle",
+      "title": "Try-with-resources",
+      "url": "https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html",
+      "section": "Closing resources and suppressed exceptions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "JDK8 tutorial; not a source for newer runtime features",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Preserve primary cause and borrowed-resource ownership; check actual API contract."
+    },
+    {
+      "id": "java-executor",
+      "publisher": "Oracle",
+      "title": "ExecutorService",
+      "url": "https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/ExecutorService.html",
+      "section": "Shutdown, termination and awaitTermination",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Java SE17 documentation",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Check target JDK; no automatic virtual-thread or JDK migration."
+    },
+    {
+      "id": "google-python",
+      "publisher": "Google",
+      "title": "Python Style Guide",
+      "url": "https://google.github.io/styleguide/pyguide.html",
+      "section": "Imports, exceptions and mutable state",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Keep current formatter/type checker and library responsibilities."
+    },
+    {
+      "id": "python-asyncio",
+      "publisher": "Python project",
+      "title": "Coroutines and tasks",
+      "url": "https://docs.python.org/3/library/asyncio-task.html",
+      "section": "Cancellation and task ownership",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed 3.15.2; feature availability follows project Python",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Newer TaskGroup/timeout features require a supported project version; no upgrade implied."
+    },
+    {
+      "id": "cert-c",
+      "publisher": "CMU SEI",
+      "title": "MEM00-C allocation and release",
+      "url": "https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/recommendations/memory-management-mem/mem00-c/",
+      "section": "MEM00-C memory responsibility",
+      "checkedAt": "2026-11-08",
+      "versionScope": "2016-edition standard family; MEM00-C is a recommendation",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Do not label recommendations as mandatory CERT rules or apply C++ ownership machinery to pure C."
+    },
+    {
+      "id": "cpp-core",
+      "publisher": "C++ Core Guidelines editors",
+      "title": "C++ Core Guidelines",
+      "url": "https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines",
+      "section": "Resource and lifetime interfaces",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page dated 2026-06-14, living release0.8",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Adapt to existing exception policy and compiler; borrowing does not imply ownership."
+    },
+    {
+      "id": "google-cpp",
+      "publisher": "Google",
+      "title": "C++ Style Guide",
+      "url": "https://google.github.io/styleguide/cppguide.html",
+      "section": "Exceptions and project consistency",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Its exception/standard policy is not universal; preserve the owning project policy and C ABI."
+    },
+    {
+      "id": "ms-sal",
+      "publisher": "Microsoft",
+      "title": "Understanding SAL",
+      "url": "https://learn.microsoft.com/en-us/cpp/code-quality/understanding-sal?view=msvc-170",
+      "section": "Parameter preconditions and output guarantees",
+      "checkedAt": "2026-11-08",
+      "versionScope": "MSVC170 documentation view",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "SAL is an optional toolchain-specific expression, not a portable mandatory annotation."
+    },
+    {
+      "id": "aws-retry",
+      "publisher": "AWS",
+      "title": "Timeouts, retries and backoff with jitter",
+      "url": "https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/",
+      "section": "Timeouts, bounded retries and retry amplification",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Article dated 2019-12-05; official Builder Center redirect",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Retry only semantically safe operations within a total budget; failure classes alone do not grant write replay."
+    },
+    {
+      "id": "aws-idempotency",
+      "publisher": "AWS",
+      "title": "Making retries safe with idempotent APIs",
+      "url": "https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/",
+      "section": "Caller intent, duplicate requests and atomic recording",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Builders Library; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "A process-local example does not establish database/multi-process exactly-once."
+    },
+    {
+      "id": "react-effects",
+      "publisher": "React project",
+      "title": "useEffect",
+      "url": "https://react.dev/reference/react/useEffect",
+      "section": "Cleanup and fetching race conditions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed React19.3; use installed project API",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Abort and stale-result checks complement each other; no React upgrade implied."
+    },
+    {
+      "id": "react-act",
+      "publisher": "React project",
+      "title": "act",
+      "url": "https://react.dev/reference/react/act",
+      "section": "Applying updates before assertions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed React19.3; verify sample versions",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "DOM simulation is not browser E2E or native desktop execution."
+    },
+    {
+      "id": "vue-watchers",
+      "publisher": "Vue project",
+      "title": "Watchers",
+      "url": "https://vuejs.org/guide/essentials/watchers.html",
+      "section": "Side-effect cleanup",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Vue3; onWatcherCleanup requires3.5+ and synchronous registration",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Use supported callback cleanup on older Vue3; no framework migration."
+    },
+    {
+      "id": "tauri-permissions",
+      "publisher": "Tauri project",
+      "title": "Permissions",
+      "url": "https://v2.tauri.app/security/permissions/",
+      "section": "Command allow/deny and capability scope",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Tauri2 docs; check installed version/configuration",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Rust command-unit tests do not activate webview permissions or prove packaged GUI security."
+    },
+    {
+      "id": "electron-security",
+      "publisher": "Electron project",
+      "title": "Security",
+      "url": "https://www.electronjs.org/docs/latest/tutorial/security",
+      "section": "IPC sender checks and renderer trust",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living docs; match installed Electron",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Handler tests do not prove sandbox/context isolation is active in a packaged app."
+    },
+    {
+      "id": "spring-tests",
+      "publisher": "Spring project",
+      "title": "Testing Spring Boot applications",
+      "url": "https://docs.spring.io/spring-boot/3.5/reference/testing/spring-boot-applications.html",
+      "section": "Test slices and application tests",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Boot3.5 docs observed3.5.16; preserve sample/project versions",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Test scope matters; MVC tests do not establish live DB/transaction or deployment behavior."
+    },
+    {
+      "id": "fastapi-lifespan",
+      "publisher": "FastAPI project",
+      "title": "Lifespan events",
+      "url": "https://fastapi.tiangolo.com/advanced/events/",
+      "section": "Acquire and release application resources",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living FastAPI documentation; match pinned dependencies",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Use actual lifespan execution in tests; import does not own a live connection."
+    },
+    {
+      "id": "gin-binding",
+      "publisher": "Gin project",
+      "title": "Binding",
+      "url": "https://gin-gonic.com/en/docs/binding/",
+      "section": "Binding errors and validation",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living Gin documentation; match pinned module",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Writing/aborting a response does not replace explicit control-flow return in the current handler."
+    },
+    {
+      "id": "axum-extractors",
+      "publisher": "Axum project",
+      "title": "Extractors",
+      "url": "https://docs.rs/axum/latest/axum/extract/",
+      "section": "Extractor order and rejections",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Latest route observed0.8.9; fixed0.8.9 route unavailable via browser tool",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Pinned existing example is authoritative for compilation; do not assume source signatures across releases."
+    },
+    {
+      "id": "drogon-filters",
+      "publisher": "Drogon project",
+      "title": "Middleware and Filter",
+      "url": "https://github.com/drogonframework/drogon/wiki/ENG-05-Middleware-and-Filter",
+      "section": "Filter callbacks and continuation",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living wiki; match compiled example version",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Synthetic role headers are not authentication; callback lifetime must follow actual ownership."
+    },
+    {
+      "id": "node-typescript",
+      "publisher": "Node.js project",
+      "title": "Modules: TypeScript",
+      "url": "https://nodejs.org/api/typescript.html",
+      "section": "Type-stripping history, enabling, and separate type checking",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed26.13.0; sample>=22.18, actual24.14.1 tested; product Node>=22 unchanged",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Native stripping is not type checking and ignores tsconfig. Missing sample capability is MISSING, not a product runtime upgrade."
+    }
+  ]
+}

package/skills/cc-go-project-standard/references/engineering-practices.md

@@ -0,0 +1,106 @@
+---
+practiceCards:
+  - id: "cc-go-project-standard:package-interfaces"
+    level: "recommended"
+    sourceIds: ["uber-go"]
+    caseIds: ["EP-GO-01"]
+    evidence: "review-only"
+  - id: "cc-go-project-standard:error-boundaries"
+    level: "required"
+    sourceIds: ["uber-go","aws-idempotency"]
+    caseIds: ["EP-GO-01","EP-SVC-01"]
+    evidence: "review-only"
+  - id: "cc-go-project-standard:context-ownership"
+    level: "conditional"
+    sourceIds: ["go-context","uber-go"]
+    caseIds: ["EP-GO-01"]
+    evidence: "case"
+---
+
+# Local engineering decisions
+
+Locate the actual role, toolchain and existing conventions, then read relevant [shared principles](common/engineering-practices.md). These conditions apply to this entry, not every project. Structure checks do not prove all semantics or execution.
+
+<a id="cc-go-project-standard:package-interfaces"></a>
+## Define dependencies where they are consumed
+
+Level: recommended
+
+### Risk
+A large provider interface couples callers to unrelated operations.
+
+### Applies
+When a package consumes replaceable behavior; small concrete internal values do not need an interface automatically.
+
+### Decision
+Locate nearest go.mod/go.work, keep import paths stable and inject the narrow behavior the consumer uses. Construct long-lived dependencies at an explicit composition entry.
+
+### Exceptions
+Keep an existing well-bounded interface if changing it brings no task benefit. Do not introduce an Uber dependency or root go get because a style guide uses one.
+
+### Examples
+Better: a library accepts its needed reader. Worse: give every type a mirror interface or require HTTP layers for a desktop module.
+
+### Verification
+Compile/test the changed module and an actual consuming package; inspect exported compatibility separately from worker-lifetime evidence.
+
+### Sources
+uber-go — [registry and limits](common/engineering-practices.sources.json).
+
+Evidence IDs: EP-GO-01; review-only.  Execution status and scope require actual records; a related ID does not prove every decision on this card.
+
+<a id="cc-go-project-standard:error-boundaries"></a>
+## Errors retain identity and operation context
+
+Level: required
+
+### Risk
+String-only errors and blind retries can hide a partially committed effect.
+
+### Applies
+For errors crossing package or transport boundaries; avoid wrapping every internal line without useful context.
+
+### Decision
+Use the current error taxonomy, errors.Is/As and appropriate wrapping to preserve identity; translate at the owning boundary and redact diagnostics. Distinguish cancellation and uncertain commit.
+
+### Exceptions
+Do not promise exactly-once from an error type. A write retry needs stable intent and a server-side idempotency contract, not just a retryable status.
+
+### Examples
+Better: caller can detect the original failure and reconcile an unknown commit. Worse: log-and-ignore then return nil.
+
+### Verification
+Inject a failure and inspect caller-visible cause/state; HTTP replay is covered by a separate service case, not the pipeline test.
+
+### Sources
+uber-go, aws-idempotency — [registry and limits](common/engineering-practices.sources.json).
+
+Evidence IDs: EP-GO-01, EP-SVC-01; review-only.  Execution status and scope require actual records; a related ID does not prove every decision on this card.
+
+<a id="cc-go-project-standard:context-ownership"></a>
+## Propagate cancellation and wait for owned work
+
+Level: conditional
+
+### Risk
+A blocked send/receive can survive cancel; cancellation alone is not joining.
+
+### Applies
+For blocking I/O or goroutines this unit owns, across library/CLI/desktop/service roles.
+
+### Decision
+Pass context through cancellable calls, select cancellation at blocking channel boundaries and retain a completion/wait mechanism. The creator owns cancel and joining its workers.
+
+### Exceptions
+A deliberate app-lifetime task needs its own explicit owner; do not retain a request context globally or close a channel from arbitrary receivers.
+
+### Examples
+Better: stop admission, cancel and wait for both workers. Worse: increase channel capacity to hide an abandoned goroutine.
+
+### Verification
+Use the local event-driven test; its watchdog bounds a missing completion, not a sleep-based ordering assumption. Race/all-schedule coverage remains separate.
+
+### Sources
+go-context, uber-go — [registry and limits](common/engineering-practices.sources.json).
+
+Evidence IDs: EP-GO-01; case. [Local runnable example](../examples/engineering/README.md). Execution status and scope require actual records; a related ID does not prove every decision on this card.

package/skills/cc-go-project-standard/references/practice.md

@@ -0,0 +1,37 @@
+# Go project engineering
+
+## Specialist checks
+
+1. Locate go.work and the nearest go.mod; preserve module import paths and dependency versions. Do not run a root-level go get simply because the task is in a submodule.
+
+2. Create dependencies at an explicit entry point and inject narrow interfaces into consumers. The creator owns closing pools, clients and background workers.
+
+3. Return actionable errors, preserve causes with wrapping, and use errors.Is/As where appropriate. Map errors at transport boundaries without leaking internals.
+
+4. Pass context through operations that can block, keep cancellation ownership explicit, and avoid storing request context in global state.
+
+5. Put behavior tests near packages; cover cancellation, empty results and downstream failures. Scope integration and race checks to the changed module.
+
+6. Check formatting without writing, run available vet and tests, and record unavailable dependencies/toolchains. Build success alone does not demonstrate test execution.
+
+<a id="scope"></a>
+## Scope and examples
+
+Use for:
+- Organize internal packages in a Go module
+- Review errors and context boundaries in a Go service
+- Add a repository adapter without global database state
+- Validate one module inside go.work
+
+A focused goroutine/channel lifecycle defect belongs to the concurrency specialty.
+
+## Evidence to deliver
+
+- Repository/contract evidence and the exact affected scope.
+- Chosen approach, invariants, resource/error or failure boundaries.
+- Commands actually run and results, unrun checks and unproven claims.
+- Compatibility, recovery/rollback or follow-up limits; review findings need verified locations.
+
+## Primary reference
+
+[Relevant official/project documentation](https://go.dev/doc/effective_go) (checked 2026-11-06). Match the actual project version before applying version-sensitive details; the page version does not authorize an upgrade.

package/skills/cc-java-project-standard/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: cc-java-project-standard
+description: "Use when Java package/module structure, build-tool conventions, application boundaries, exceptions, persistence ownership or repository-wide Java engineering needs design or review."
+---
+
+# Java project engineering
+
+Apply to libraries, CLI tools, desktop cores and services. Determine the application role from the actual project; a frontend/backend product name does not constrain the language.
+
+Read the declared JDK, build descriptor, wrapper and existing package layering. Preserve the current language level and dependency platform.
+
+## Apply the workflow
+
+1. Locate the actual project, task boundary and existing contracts; load only the language and domain material needed now.
+2. Apply the [specialist checks](references/practice.md), establishing the input evidence before selecting the smallest change.
+3. Verify affected behavior with existing repository tools. Explicitly report missing tools, environments or execution; a plan is not a passing result.
+4. Deliver scope, specialist decisions, actual verification and remaining risk. A review-only task stays read-only.
+
+## Task boundary
+
+JVM profiling and pool/GC incidents belong to the runtime specialty; do not impose a particular web framework.
+
+## Engineering practices
+
+Read the [local engineering decisions](references/engineering-practices.md) for this task and follow their links to relevant shared principles. Apply levels and exceptions against actual project contracts; product frontend/backend labels do not constrain language or role.

package/skills/cc-java-project-standard/examples/engineering/README.md

@@ -0,0 +1,7 @@
+# Partial initialization and cause — EP-JAVA-01
+
+In a writable copy, prepare with `javac --release 17 ResourceBoundary.java ResourceBoundaryTest.java`. Run `java -ea -cp . ResourceBoundaryTest` with `CRAFT_ENGINEERING_DEFECTIVE=1`, then `=0` (the protected default). PowerShell assigns `$env:CRAFT_ENGINEERING_DEFECTIVE`; POSIX prefixes the command. No third-party library or repository source is required.
+
+The failure test observes the real original IOException and exactly one release callback. The defect omits failure-path close. Both named tests use always-active require checks; disabling Java assertions does not turn them into empty tests. The JSON lines summarize executed test bodies; the verifier checks names, counters, exit code and actual failure marker together.
+
+Java17 is this example's compile target, not a required project upgrade. This is not an executor, GUI, database-driver or suppressed-close-error test. Keep .class/log output in the writable copy; verify those additional boundaries separately.

package/skills/cc-java-project-standard/examples/engineering/ResourceBoundary.java

@@ -0,0 +1,26 @@
+import java.io.IOException;
+
+public final class ResourceBoundary {
+  private ResourceBoundary() {}
+  public static final class BoundaryFailure extends Exception {
+    BoundaryFailure(IOException cause) { super("payload initialization failed", cause); }
+  }
+  private static final class Lease implements AutoCloseable {
+    private final Runnable release;
+    Lease(Runnable release) { this.release = release; }
+    @Override public void close() { release.run(); }
+  }
+  public static void open(boolean fail, Runnable release) throws BoundaryFailure {
+    Lease lease = new Lease(release);
+    if ("1".equals(System.getenv("CRAFT_ENGINEERING_DEFECTIVE"))) {
+      if (fail) throw new BoundaryFailure(new IOException("payload unavailable"));
+      lease.close();
+      return;
+    }
+    try (lease) {
+      if (fail) throw new IOException("payload unavailable");
+    } catch (IOException cause) {
+      throw new BoundaryFailure(cause);
+    }
+  }
+}

package/skills/cc-java-project-standard/examples/engineering/ResourceBoundaryTest.java

@@ -0,0 +1,41 @@
+import java.io.IOException;
+import java.util.concurrent.atomic.AtomicInteger;
+
+public final class ResourceBoundaryTest {
+  private static int passed;
+  private static int failed;
+  @FunctionalInterface private interface Checked { void run() throws Exception; }
+  private static void require(boolean condition, String message) {
+    if (!condition) throw new AssertionError(message); // Always active, with or without -ea.
+  }
+  private static void run(String name, Checked body) {
+    try {
+      body.run(); passed++;
+      System.out.println("CRAFT_TEST {\"name\":\"" + name + "\",\"status\":\"pass\"}");
+    } catch (Exception | AssertionError error) {
+      failed++;
+      System.err.println("CRAFT_ASSERTION: " + error);
+      System.out.println("CRAFT_TEST {\"name\":\"" + name + "\",\"status\":\"fail\"}");
+    }
+  }
+  public static void main(String[] args) {
+    run("failure_closes_and_preserves_cause", () -> {
+      AtomicInteger closes = new AtomicInteger();
+      try {
+        ResourceBoundary.open(true, closes::incrementAndGet);
+        throw new AssertionError("expected initialization failure");
+      } catch (ResourceBoundary.BoundaryFailure error) {
+        require(error.getCause() instanceof IOException, "EP-JAVA-01 original I/O cause required");
+        require("payload unavailable".equals(error.getCause().getMessage()), "EP-JAVA-01 cause message required");
+        require(closes.get() == 1, "EP-JAVA-01 acquired lease must close once");
+      }
+    });
+    run("success_closes_once", () -> {
+      AtomicInteger closes = new AtomicInteger();
+      ResourceBoundary.open(false, closes::incrementAndGet);
+      require(closes.get() == 1, "EP-JAVA-01 successful lease closes once");
+    });
+    System.out.println("CRAFT_SUMMARY {\"total\":2,\"passed\":"+passed+",\"failed\":"+failed+",\"skipped\":0}");
+    if (failed != 0) System.exit(1);
+  }
+}