@scalemule/news-publication 0.0.80 → 0.0.82

package/README.md

@@ -328,15 +328,88 @@ The publisher-supplied `PawMark` preserves the approved SVG paths. Hosts may set
 
 ### Standard article submission
 
-Server tools and authorized agents use `PublicationArticleClient` from
-`@scalemule/news-publication/article-workflow`. Discover `options()` first;
-require `workflow_version: 1`. Use `submitArticle()` for a private draft plus
-managed photo staging, or `get()` and `save()` for a generation-fenced edit.
-Keep the operation key when resuming. Editorial approval and release remain
-explicit commands; acceptance does not certify scan, image or audio completion.
-The platform contract and a complete example live in
-`docs/news-platform/ARTICLE-WORKFLOW-V1.md` in the ScaleMule meta-repo.
-Do not use direct SQL, S3 paths, base64 bodies or invented media readiness.
+Submit through the server-owned API using `PublicationArticleClient` from
+`@scalemule/news-publication/article-workflow`:
+
+```ts
+const receipt = await client.submitArticle({
+  operationKey: "story-intake-v1", authorProfileId: authorId,
+  document: { title, content_markdown: body, section: "Local Business" },
+  intent: "publish",
+  assets: [{ file: photo, filename: "venue.jpg", position: "hero",
+    metadata: { alt: "Exterior of the actual venue", credit: "Photographer",
+      rights_confirmed: true } }],
+});
+```
+
+This sends **one POST** to `/v1/blog/publications/{id}/submissions`, with a
+multipart manifest and its files. JSON without files is supported by
+`client.submit(manifest, key)`. The same API accepts `article.operation: "save"`
+with the existing article ID, expected generation, complete document and revision
+reason. The server owns private Photo/Storage intake, scan checks, immutable
+media attachment, required private narration and release. Optional narration
+and missing-visual commissioning use the existing post-publication workers.
+Existing subject/editorial/sensitivity approvals still apply. `draft` is the
+safe default; `publish` requests release after the configured gates.
+
+An accepted receipt is **not** a claim that media is ready or a page has been
+verified. Read `client.submission(receipt.submission_id)` for holds, processing
+and public readiness. After a timeout, replay the identical manifest, files and
+operation key. Do not re-upload through other endpoints or create a new article.
+A foreign revision, rejected media, expired replay or unconfirmed asset intake
+stops with a retained receipt rather than silently overwriting or duplicating.
+No client-side fallback performs a separate multi-service publishing sequence.
+Discover `managed_submission_version: 1` before adopting this endpoint on an
+older server. Supported files are still JPEG/PNG/WebP photographs, not video or
+animation. Never use SQL, S3 paths, embedded binary or invented ready flags.
+
+CLI equivalents:
+
+```sh
+scalemule-article submit --publication "$PUBLICATION_ID" \
+  --manifest article.json --asset hero=./venue.jpg --operation-key story-intake-v1
+scalemule-article status --publication "$PUBLICATION_ID" --submission "$SUBMISSION_ID"
+```
+
+The manifest uses the API's snake_case fields: `article`, `intent`, and optional
+`assets: [{slot: "hero", position: "hero", metadata: {...}}]`. Each `--asset`
+matches one declared slot. Credentials are normal project/member credentials.
+The operation key is retained for 30 days. A legacy article must first have an
+explicitly selected collaboration policy; this endpoint never downgrades review.
+
+### Edit article prose, cards and citations
+
+```sh
+npx --yes --package @scalemule/news-publication@0.0.81 scalemule-article edit \
+  --url "$ARTICLE_URL" --patch ./approved-edit.json --operation-key correction-v1
+```
+
+The patch may contain title, subtitle, content_markdown, excerpt, section,
+community, format, layout, cards and citations. It preserves omitted fields and
+media and saves one immutable revision. Default: save for review. Add
+`--release` only to request release through the existing policy; the command
+never issues APPROVE or downgrades review. On a legacy article, explicitly choose
+`--enable-review-policy` only as a legitimate editorial onboarding decision.
+Scheduled legacy articles stop before onboarding. Normal API-key/member grants
+remain authoritative; the deployed server must advertise
+`versioned_editorial_fields`.
+
+The 10-second default deadline bounds the operation; `--timeout-ms` may raise it
+to at most 120 seconds. Keep the same patch/key and private checkpoint
+(`--state` or `~/.scalemule/newsroom/operations`) on retries. The checkpoint
+contains the submitted document and private provenance: never publish it.
+Unknown save/release responses reconcile against the original revision; another
+current revision stops rather than being overwritten. Completed replay and no-op
+edits add no revision. `RELEASE_HELD`/exit 2 preserves the saved revision while
+review is pending. With `--url --release`, success requires the rendered
+headline, prose and actual card components; public visibility pending is also
+exit 2. A saved revision and a rendered published correction are separate states.
+
+Use the same client method, `client.editArticle`, for a caller-supplied durable
+checkpoint store. This is local resumability over the existing server save
+receipt, not a distributed transaction covering entities, syndication, media
+commissioning or human review. The notices-only `/editorial` endpoint is not
+an article-body/card editor. Routine content corrections require no backend PR.
 
 ### Replace a published article photo from a local file
 

package/bin/scalemule-article.mjs

@@ -1,20 +1,32 @@
 #!/usr/bin/env node
-import { readFile, mkdir, writeFile, rename, open, unlink } from 'node:fs/promises';
+import { readFile, stat, mkdir, writeFile, rename, open, unlink } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join, basename } from 'node:path';
 import { createHash } from 'node:crypto';
 import { parseArgs } from 'node:util';
-import { PublicationArticleClient, articlePhotoHtmlMatches } from '../dist/article-workflow-client.js';
+import { PublicationArticleClient, articlePhotoHtmlMatches,articleEditHtmlMatches } from '../dist/article-workflow-client.js';
 
 const help = `Usage:
+  scalemule-article submit --publication ID --manifest article.json --operation-key KEY [--asset hero=/path/photo.jpg]
+  scalemule-article status --publication ID --submission ID
   scalemule-article inspect --publication ID --article ID
   scalemule-article replace-cover --publication ID --article ID --file-id ID --expected-version N --metadata photo.json
   scalemule-article replace-photo --url ARTICLE_URL --file PHOTO --metadata photo.json --operation-key KEY
+  scalemule-article edit --url ARTICLE_URL --patch edit.json --operation-key KEY [--release]
 
 Credentials: SCALEMULE_API_KEY and SCALEMULE_ACCESS_TOKEN (normal authorized member).
 Platform admins may use their normal access token with --application-id ID.
 Optional --api-url URL defaults to https://api.scalemule.com.
 
+edit saves prose, excerpt, cards and citations in one immutable revision.
+Unspecified fields and media are retained. Default: save for review.
+--release explicitly requests release under the existing policy; it never issues
+APPROVE or changes a policy. Legacy onboarding requires an explicit
+--enable-review-policy value. Scheduled legacy articles stop before onboarding.
+Use --expected-generation when coordinating an edit with another editor.
+Default edit deadline: 10000 ms. Reuse the same patch/key/checkpoint on retry.
+RELEASE_HELD means the revision is saved and existing review gates remain.
+
 replace-photo accepts a local file and uses normal member/API-key credentials.
 It requires developer-level asset access and publication approval rights.
 It resolves the publication from its authorized API inventory, saves a private
@@ -44,17 +56,17 @@ that every website/CDN cache already displays the new image.
 try {
   const { values, positionals } = parseArgs({
     allowPositionals: true, strict: true,
-    options: Object.fromEntries(['publication', 'article', 'file-id', 'expected-version', 'metadata', 'application-id', 'api-url', 'url', 'file', 'operation-key', 'state', 'timeout-ms'].map(k => [k, { type: 'string' }]).concat([['help', { type: 'boolean' }]])),
+    options: Object.fromEntries(['publication', 'article', 'file-id', 'expected-version', 'metadata', 'application-id', 'api-url', 'url', 'file', 'operation-key', 'state', 'timeout-ms','patch','expected-generation','enable-review-policy','manifest','submission'].map(k => [k, { type: 'string' }]).concat([['asset',{type:'string',multiple:true}],['help', { type: 'boolean' }],['release',{type:'boolean'}]])),
   });
   if (values.help || !positionals.length) {
     console.log(help);
   } else {
     const [command, ...extra] = positionals;
     const commandStarted = performance.now();
-    const budget = Number(values['timeout-ms'] ?? 30000);
+    const budget = Number(values['timeout-ms'] ?? (command==='edit'?10000:30000));
     if (!Number.isFinite(budget) || budget < 100 || budget > 120000) throw Error('--timeout-ms must be between 100 and 120000');
     const remaining = () => { const ms = Math.floor(budget - (performance.now()-commandStarted)); if (ms < 1) throw Error('Operation deadline reached; resume the same operation'); return ms; };
-    if (extra.length || !['inspect', 'replace-cover', 'replace-photo'].includes(command)) throw Error('Use inspect, replace-cover or replace-photo; see --help');
+    if (extra.length || !['submit','status','inspect', 'replace-cover', 'replace-photo','edit'].includes(command)) throw Error('Use submit, status, inspect, edit, replace-cover or replace-photo; see --help');
     if (values.url) {
       if (!process.env.SCALEMULE_API_KEY || !process.env.SCALEMULE_ACCESS_TOKEN || values['application-id']) throw Error('URL resolution requires normal publication member/API-key credentials');
       const url = new URL(values.url);
@@ -73,7 +85,7 @@ try {
       if ((values.publication && values.publication !== pub.id) || (values.article && values.article !== resolved.article.id)) throw Error('Article URL and supplied IDs disagree');
       values.publication = pub.id; values.article = resolved.article.id;
     }
-    for (const key of ['publication', 'article']) if (!values[key]) throw Error(`Missing --${key}`);
+    for (const key of (['submit','status'].includes(command)?['publication']:['publication','article'])) if (!values[key]) throw Error(`Missing --${key}`);
     if (!process.env.SCALEMULE_ACCESS_TOKEN) throw Error('SCALEMULE_ACCESS_TOKEN is required; use normal member or platform admin authorization');
     if (!values['application-id'] && !process.env.SCALEMULE_API_KEY) throw Error('Member calls also require SCALEMULE_API_KEY');
     const client = new PublicationArticleClient({
@@ -84,7 +96,22 @@ try {
       accessToken: process.env.SCALEMULE_ACCESS_TOKEN,
     });
     const started = performance.now();
-    if (command === 'inspect') {
+    if(command==='submit'){
+      for(const key of ['manifest','operation-key'])if(!values[key])throw Error('Missing --'+key);
+      const manifest=JSON.parse(await readFile(values.manifest,'utf8'));
+      const assets=[];
+      for(const entry of values.asset??[]){
+        const split=entry.indexOf('=');if(split<1)throw Error('--asset must be slot=/path/to/photo');
+        const slot=entry.slice(0,split),path=entry.slice(split+1);
+        const info=await stat(path);if(!info.isFile()||info.size<1||info.size>25*1024*1024)throw Error('Photo must be a regular file between 1 byte and 25 MiB');
+        assets.push({slot,filename:basename(path),file:new Blob([await readFile(path)])});
+      }
+      const receipt=await client.submit(manifest,values['operation-key'],assets,AbortSignal.timeout(remaining()));
+      console.log(JSON.stringify({...receipt,elapsed_ms:Math.round(performance.now()-started)},null,2));
+    }else if(command==='status'){
+      if(!values.submission)throw Error('Missing --submission');
+      console.log(JSON.stringify(await client.submission(values.submission,AbortSignal.timeout(remaining())),null,2));
+    }else if (command === 'inspect') {
       const [options, processing, collaboration] = await Promise.all([
         client.options(values.article), client.processing(values.article),
         client.get(values.article).then(current => ({ enabled: true, generation: current.generation, status: current.status })).catch(error => {
@@ -99,6 +126,47 @@ try {
         capabilities: options.capabilities, narration: processing.narration,
         assets: processing.assets, collaboration, elapsed_ms: Math.round(performance.now() - started),
       }, null, 2));
+    } else if (command==='edit') {
+      for(const key of ['patch','operation-key'])if(!values[key])throw Error('Missing --'+key);
+      const patch=JSON.parse(await readFile(values.patch,'utf8'));
+      const key=createHash('sha256').update(JSON.stringify(['edit',values['api-url']??'https://api.scalemule.com',values.publication,values.article,values['operation-key']])).digest('hex');
+      const statePath=values.state??join(homedir(),'.scalemule','newsroom','operations',key+'.json');
+      await mkdir(dirname(statePath),{recursive:true,mode:0o700});
+      const lockPath=statePath+'.lock';let lock;
+      try{lock=await open(lockPath,'wx',0o600);}catch(error){
+        if(error.code!=='EEXIST')throw error;
+        const pid=Number(await readFile(lockPath,'utf8'));if(!Number.isSafeInteger(pid)||pid<1)throw Error('Invalid operation lock; inspect '+lockPath);
+        let alive=true;try{process.kill(pid,0);}catch(e){if(e.code==='ESRCH')alive=false;else throw e;}
+        if(alive)throw Error('This edit operation is already running');
+        await unlink(lockPath);lock=await open(lockPath,'wx',0o600);
+      }
+      await lock.writeFile(String(process.pid));await lock.close();
+      try{
+        let checkpoint;try{checkpoint=JSON.parse(await readFile(statePath,'utf8'));}catch(error){if(error.code!=='ENOENT')throw error;}
+        const result=await client.editArticle({articleId:values.article,operationKey:values['operation-key'],patch,
+          expectedGeneration:values['expected-generation']===undefined?undefined:Number(values['expected-generation']),
+          enableReviewPolicy:values['enable-review-policy'],release:values.release,checkpoint,timeoutMs:remaining(),
+          saveCheckpoint:async state=>{const temp=statePath+'.'+process.pid+'.tmp';await writeFile(temp,JSON.stringify(state),{mode:0o600});await rename(temp,statePath);checkpoint=state;},
+        });
+        if(values.url&&values.release&&['published','already_published'].includes(result.state)){
+          let verified=false,reason;
+          try{
+            const snapshot=await client.publicArticle(checkpoint.sourceIdentity.slug,AbortSignal.timeout(remaining()));
+            const article=snapshot.article;
+            if(!article||!article.content_html||article.id!==values.article)throw Error('Published reader snapshot is missing');
+            while(!verified){
+              const response=await fetch(values.url,{redirect:'error',cache:'no-store',signal:AbortSignal.timeout(Math.min(5000,remaining()))});
+              const html=await response.text();
+              verified=response.ok&&articleEditHtmlMatches(html,{title:article.title,content_html:article.content_html,card_titles:(article.metadata?.cards??[]).map(c=>c.title)});
+              if(!verified)await new Promise(r=>setTimeout(r,Math.min(300,remaining())));
+            }
+          }catch(error){reason=error.message;}
+          if(!verified){console.error(JSON.stringify({...result,state:'published_public_verification_pending',stage:'public_page',message:'The exact revision is published; rendered prose/cards remain unverified. Resume the same edit.',reason}));process.exitCode=2;}
+          else console.log(JSON.stringify({...result,public_page_verified:true,total_elapsed_ms:Math.round(performance.now()-commandStarted)},null,2));
+        }else{
+        console.log(JSON.stringify({...result,total_elapsed_ms:Math.round(performance.now()-commandStarted)},null,2));
+        }
+      }finally{await unlink(lockPath);}
     } else if (command === 'replace-photo') {
       for (const key of ['file','metadata','operation-key']) if (!values[key]) throw Error(`Missing --${key}`);
       if (values['application-id']) throw Error('Local-photo intake uses normal publication member credentials');
@@ -182,6 +250,6 @@ try {
     }
   }
 } catch (error) {
-  console.error(JSON.stringify({ error: error.message, status: error.status, code:error.code, stage:error.stage, file_id:error.fileId }));
-  process.exitCode = 1;
+  console.error(JSON.stringify({ error: error.message, status: error.status, code:error.code, stage:error.stage, file_id:error.fileId,revision_id:error.revisionId }));
+  process.exitCode = error.code==='RELEASE_HELD'?2:1;
 }